このフォルダに SKILL.local.md が存在する場合は、最初にそれを読んでください。そこにはパス、データ、およびハウスルールが記載されています。
深度スクロール
読者が1つずつ体験する一連の図版のためのページ形式です。最初のビルドでは、WhatTheFad(whatthefad.netlify.app、ソースは github.com/rafaelcarlosabbariao/cultural-archaeology)のランディングページをモデルに、一連の説明図を視聴者に向かってスクロールする形式に変換しました。
このスキルには次の4つのファイルが含まれます。
| ファイル | 説明 |
|---|---|
template.html | ページ:ステーションチャーム、ストリーム、レール、およびそれらを動作させるスクリプト |
build.py | スペック指定からテンプレートを埋める。コマンドまたはモジュールとして使用可能 |
capture.mjs | DevTools プロトコルを介したリアルタイムのヘッドレスキャプチャとナビゲーションチェック |
SKILL.md | このファイル |
適した用途
- 適している:4~12個の自己完結型パネルを1つずつ読む場合。各パネルは画面に収まる大きさ:図面、ワンアイデアカード、シーケンスの各段階。
- 適さない:長い散文、表、または読者が左右に比較したり前後にスキャンするようなコンテンツ。そのような場合はフラットページを構築してください。
- 出力:ページは1つの自己完結型
.htmlファイルで、外部スクリプトやWebGLは不要です。テンプレートには:rootトークンに暖かいクリームとインクのパレットが同梱されています。必要に応じてスタイルを変更してください。
仕組み
WhatTheFadのフィールド、ソース
WhatTheFad の index.html(#landing-trendfield CSS と renderTrendField 関数)を参照してください。
- 投影:フィールドは
perspective: 900pxのコンテナで、各チップはtranslate3d(x, y, z)で配置されます。ブラウザはチップを 900 / (900 − z) のスケールで描画します:z = −2800 で0.24、画面平面で1、z = 220 で1.3。 - クロックが動きを駆動:
requestAnimationFrameループが各チップを毎秒150px(チップごとに0.75〜1.25の係数を乗算)で視聴者に向かって移動させます。z = 220 を超えると、z = −2800 の楕円リング上に再出現します。 - フェードと描画順:チップは深度の最初の4分の1でフェードインし、z = 60 から 220 の間でフェードアウトします。フィールドは
preserve-3dを使用しないため、各チップのz-indexは深度から設定され、手前のチップが上に描画されます。 - 静かな中心:放射状の
mask-imageで中央を隠し、遠くのチップが消失点に集まるのを防ぎます。 - チップのキャッチ:ブラウザはポインターが移動したときのみ
:hoverを再チェックするため、静止したカーソルの下をチップが漂っても光りません。WhatTheFad は毎フレーム、各チップの投影矩形に対してポインターをテストし、キャッチされたチップはフィールドの速度を8%に減速します。
このフォーマットが追加するもの
- スクロールがカメラになる。
- 高さのあるトラック(
main.depth)は、ステーションごとに1ストップ、ステージの高さ1つ分の間隔で保持し、scroll-snap-type: y proximityを備えます。 - 固定ヘッダーの下のスティッキーステージがシーンを保持します。
- スクロール位置はステーションインデックスになり、各ストップで整数値になります。カメラはそれに向かってイーズ(毎秒9のレート)し、ステーション
iは z = (カメラ − i) × 1400 で描画されます。
- 高さのあるトラック(
- ステーションの通過。
- 待機中の後方のステーションは薄暗く、少し低い位置にあるため、前方に来るときに所定の位置に浮かび上がります。
- 静止時は z = 0、スケール1、整数ピクセル上にあるため、テキストはフラットページと同じくらい鮮明です。
- 視聴者を通過すると、z = 300 でフェードアウトし、スケールは1.5倍になります。
- ステージより高いステーションは収まるようにスケーリングされます。
- ストリーム:WhatTheFad のフィールド(マスクを含む)。カードの速度はベース46にカメラ速度の0.9を加えたもので、前方にスクロールするとカードは高速で通り過ぎ、後方にスクロールすると遠ざかります。ステーションは描画するカードグループ(
lit)を指定し、そのカードはステーションが前面にある間は光ります。 - 入力。
- ホイール、トラックパッド、タッチ、矢印キー、レール、ヘッダーのコンテンツはすべて1つのネイティブスクロールを動かすため、すべての入力が同じストップに到達します。
- フォーカスが前面にないステーションに入ると、そのステーションまでスクロールします。
- ストリームは装飾的であり、静止中のステーションのみがポインターイベントを受け取るため、フレームごとのヒットテストは不要です。
- フォールバック:JavaScript がない場合、または
prefers-reduced-motion: reduceの場合、ページはステーションが平らに積み重なった状態になります。深度はスクリプトが追加するdeepクラスによって有効になります。フラットモードでは、コンテンツのアンカーがステーション上に移動します。
ビルド方法
以下で SK はこのスキルをインストールした場所(例:~/.claude/skills/depth-scroll)を示します。
- コンテンツを先に準備:各パネルをフラットページ上で
<figure class="fig">として配置し、.plate(図面)とfigcaptionを含めます。フラットページはそのまま読み取り用コピーとしても機能します。ステーションは代わりに生のhtmlを保持することもできます。 - スペックを書く(下記参照):JSONファイルとして、または値が動的に計算される場合(例:データファイルから読み取ったカード名)はプロジェクトのビルドスクリプト内の辞書として記述します。
- ビルドする:
または、スクリプトから:python3 -I $SK/build.py spec.jsonsys.path.insert(0, str(Path.home() / '.claude/skills/depth-scroll')) import build build.write(spec, base=HERE) - オプションのヘッダー:テンプレートには固定ヘッダー(
--pin-h、header.pin、nav.pin-toc)のためのスペースが確保されています。ヘッダーがない場合、ステージはウィンドウの最上部から始まります。 - 確認する:
capture.mjs(下記参照)を使用して確認し、コミットします。
スペック
パスは base(スペックファイルのフォルダ、または write に渡されたフォルダ)からの相対パスです。画像パスはそのままページに書き込まれるため、出力ページからの相対パスを指定してください。
| フィールド | 説明 |
|---|---|
out | 書き出すページ |
title | <title>。種類で命名(<主題> <種類名詞>) |
source | オプションのフラットページ。その figure.fig ブロックは fig: n になり、スタイルブロック(ヘッダー以外)はコピーされるため、図面はそのクラスを維持します |
kicker | セクションレベルのステーション上の小さなラベル。サブセクションのキッカーはセクション名です |
door | 最初のステーションのHTML:スタンドファースト、メモ、フラットページへのリンク |
stations[] | id;sec および/または sub(コンテンツ行。sec のみでセクション、sub のみでサブセクション、両方でこのステーションにセクションを開始);title(デフォルトは sub、次に sec);lead(HTML、1~2文);fig または html;cards([{img, label}]、小さな画像行);lit(光らせるストリームグループ) |
cards_label | ステーションの画像行の末尾のラベル |
close | 最後のステーション(通常はソース)の {title, kicker, html} |
stream[] | カードごとの {label, img, group}。40~80枚でストリームとして機能します |
css | オプションの追加CSS、最後に追加 |
確認
K=$SK/capture.mjs
node $K file:///path/page.html at-2.png 2 # 静止中のステーション
node $K file:///path/page.html transit.png 4.4 --wait=900 # 2つのステーション間、スナップオフ
node $K file:///path/page.html last.png 9 # 最後のストップに到達可能
node $K file:///path/page.html light.png 5 --light # デイライトグラウンド
node $K file:///path/page.html phone.png 3 375 700 # 電話幅
node $K file:///path/page.html flat.png 0 --reduce # reduced-motion ページ
node $K "file:///path/page.html#st-model" hash.png - # ストップへのリンク、読み込み時
node $K file:///path/page.html nav.png 0 --nav # 矢印、最後のコンテンツリンク、レール
各実行はストップを出力し、ステップごとに y、front(ポインターイベントを受け取るステーション)、rail、cardsShown、cardsLit、deep、pageWidth を表示します。静止中のステーションでは front がそのインデックスと等しくなります。pageWidth はビューポート幅を読み取る必要があります(横方向のページスクロールがないこと)。両方のグラウンドと電話幅で全ての画像を確認してから完了とします。画像がフォルダの外にあるページの場合は、最初に絶対パスで画像をスクラッチパッドにコピーしてください。
chrome --headless --screenshot で確認しないでください。--virtual-time-budget 下ではアニメーションフレームがほとんど進まないため、イーズされたカメラが到着せず、スクロールされたウィンドウのスクリーンショットが空白になる可能性があります。capture.mjs はリアルタイムのヘッドレスChromeを駆動し、フレームは実際のレートで実行されます。
チューニング
定数は template.html のスクリプトの先頭にあります。
| 定数 | 値 | 影響するもの |
|---|---|---|
PERSP | 900 | CSS の .stations と .field の perspective と一致する必要があります |
GAP | 1400 | 2つのステーション間のワールド深度 |
AHEAD | 2.2 × GAP | ステーションがまったく描画される前方距離 |
PASS | 300 | 通過するステーションがフェードアウトする場所(スケール1.5) |
LIFT | 36 | 待機中のステーションが距離 GAP あたり低く座るピクセル数 |
DEPTH、NEAR | 2800、220 | ストリームの生成深度と、カードが飛び去った深度 |
BASE | 46 | ストリームの静止時の速度(px/s) |
| カメライーズ | 毎秒9 | カメラがスクロールに追いつく速度 |
最初のビルドで問題だった点
これらはすべて確認によって発見され、テンプレートで修正済みです。
- ヘッダーのスクロールマージン:固定ヘッダーはすべての
[id]にscroll-margin-topを与えるため、アンカーはヘッダーの下に着地します。ストップがゼロに設定されるまで、ジャンプは各ストップより126px短く着地していました。 - トラックがヘッダー1つ分短かった:最後のストップが最上部に到達する前にページが終了していました。トラックの高さはウィンドウの高さを使用し、ステージの高さではありません。
- カードがコンテンツ列の後ろを飛んでいた:その列は固定されていて透明なため、カードがテキストを通して見えていました。列が固定されている場合、ステージはその右側から始まります。
- 遠くのカードが消失点に集まっていた:WhatTheFad のマスクで修正されました。
- 通過するステーションが大きなぼやけとして残っていた:修正はより短い
PASSと二乗フェードでした。 - 待機中のステーションが短いステーションの下に表示されていた:薄暗く(二乗で)描画されるようになりました。
- フラットモードのコンテンツが隠れたストップを指していた:ストップがステーション上に移動するようになりました。
- load イベントの前に着地したスクロールが短いページにヒットしていた:トラックはドキュメントが解析されるとすぐにレイアウトされ、フォントと画像が落ち着いた後にもう一度レイアウトされるため、復元されたスクロールと
#st-<id>リンクの両方が着地します。 - 電話上で:幅の広い図面がプレート内で横にパンし、画像行は非表示になり、ステーションは狭くなるため、レールが右端を保持します。
未解決
- カードのキャッチ:WhatTheFad では、キャッチされたチップは発掘を開きます。ここでは、カードがそのレコードを開く可能性があります。そのためには、ターゲットページがURLにIDを受け取り、上記の投影ヒットテストが必要です。
- 一時停止コントロール:ストリームはページが開かれている限り動き続けます。動きの軽減は停止しますが、WCAG 2.2.2 が他のコンテンツと並んで5秒以上続く動きに求めるような、一時停止ボタンはありません。
- 実際のトラックパッドと電話での感触、およびフレームレートは、まだ人間によって評価されていません。