@yadeck/create-slide 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yadeck/create-slide",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "YADECK: scaffold a deck repository (npx @yadeck/create-slide my-deck)",
5
5
  "homepage": "https://onfi.github.io/yadeck/",
6
6
  "repository": {
@@ -1,8 +1,101 @@
1
1
  # AGENTS.md
2
2
 
3
- このリポジトリは YADECK のスライド(deck)。`decks/*.yaml` が data、`src/` が自作プラグイン、`theme.css` がテーマ。
3
+ このリポジトリは YADECK のスライド(deck)です。YADECK は、data(YAML)に「何を伝えるか」だけを書き、見た目は view(React の Layout)が決めるスライドジェネレータです。
4
4
 
5
- - スライドの追加・編集は skill `yadeck`(`.agents/skills/yadeck/SKILL.md`)の原則と手順に従う。Claude Code / Codex / Antigravity それぞれの skill ディレクトリから同じファイルを参照している
6
- - `npm run dev` でプレビュー(http://localhost:3000/)、`npm run build` で `dist/*.html`、`npx yadeck validate` で data の検証、`npm run schema` で使える tags とフィールドの一覧(`.slide/deck.schema.json`)を生成
7
- - 見た目の変更はツール側(`@yadeck/slide-components-basic`)か `src/` のプラグインで行い、data に見た目の情報を足さない
8
- - skill を最新にするには `npx skills add onfi/yadeck --skill yadeck -y`(既存の skill を上書きする。一度これで入れた後は `npx skills update yadeck` でもよい)。YADECK のドキュメントは https://onfi.github.io/yadeck/
5
+ - ドキュメント: https://onfi.github.io/yadeck/
6
+ - スライドの追加・編集の手順: skill `yadeck`(`.agents/skills/yadeck/SKILL.md`)。Claude Code / Codex / Antigravity のどれからも同じファイルを読む
7
+
8
+ ## 構成
9
+
10
+ | パス | 中身 |
11
+ |---|---|
12
+ | `decks/*.yaml` | スライドの data。1 ファイルが 1 deck で、ファイル名が出力の HTML 名になる |
13
+ | `slide.config.ts` | 使うプラグイン、テーマ、フォント、公開先の URL などの設定 |
14
+ | `theme.css` | 色・フォント・文字サイズのトークン(Tailwind v4 の `@theme`) |
15
+ | `src/` | このリポジトリだけで使う Layout(独自テンプレート) |
16
+ | `public/` | 画像などの素材。deck からは `./name.png` で参照する |
17
+ | `.slide/deck.schema.json` | 使える tags とフィールドの一覧。`npm run schema` で作る。手で編集しない |
18
+ | `dist/` | build の出力。手で編集しない |
19
+
20
+ ## コマンド
21
+
22
+ | コマンド | 使いどころ |
23
+ |---|---|
24
+ | `npm run dev` | プレビュー(http://localhost:3000/)。保存すると自動で再読み込み |
25
+ | `npx yadeck validate` | data を書いたら必ず。知らないフィールドや型の誤りを見つける |
26
+ | `npm run schema` | 使える tags とフィールドを確かめたいとき。`src/` を変えたとき |
27
+ | `npx yadeck check --deck <deck> --slide <n> --png` | 書いたページの見た目の検査。`n` は右下のページ番号か、`$id` で付けた名前 |
28
+ | `npx yadeck png --deck <deck>` | 全ページを `dist/png/<deck>/s09.png` に書き出す |
29
+ | `npm run build` | 公開用の `dist/*.html` を作る |
30
+
31
+ ## 作業の約束
32
+
33
+ - **1 ページずつ、中身の合意を先に取る。** YAML に書く前に、見出し・説明・画面に出す文面やコードを、そのまま見せて確認する。ビルドや見た目の確認は中身が決まってから。候補は推奨を先頭に出し、利用者が選んでも直接指示してもよい形にする
34
+ - **data に見た目を書かない。** 色・位置・大きさのフィールドを足さない。`focus` は「このページで一番見てほしいもの」という中身の指定なので使ってよい
35
+ - **見せ方は tags で選ぶ。** 欲しい見せ方の Layout が無ければ、data を曲げて近い見た目にせず、「その Layout は無い」と報告する(下の「見せ方が足りないとき」)
36
+ - **入力に無いものを補わない。** 原稿やメモに無い数値・名前・文を足さない。要るなら聞く
37
+ - **原稿は `note` にそのまま入れる。** 話す文は画面に載せず、発表者モードのノートに回す
38
+ - **ページは名前で指す。** 何度も手を入れるページには `$id` で名前を付ける(URL の `#名前`、`check --slide 名前`)。ページ番号は前にページを足すとずれる
39
+ - **事実には出典を付ける。** 仕様・数値・引用・コマンドの出力を載せたページは、`sources` に一次資料の URL を書く。実在を確かめた URL だけを書く
40
+ - **確認は `yadeck check` で行う。** error(はみ出し・切れ)は直してから見せる。warn(余白への食い込み、コードの縮み・折り返し)は報告に添える。目で確かめるときは書き出した PNG を読み、ブラウザ操作のツールでスクリーンショットを撮らない
41
+
42
+ ## ページの組み立て方
43
+
44
+ skill `yadeck` の手順に従う。要点は次のとおり。
45
+
46
+ - **why → how → what の順に考える。** 載せる情報から考え始めない
47
+ - why: このページで聴衆に伝えたいことを 1 文にする(これが見出し)。聴衆がこの時点で知っていること(前提)も決める
48
+ - how: 構成の型を「配置 × 主役」で選ぶ。1 ページ 1 点
49
+ - what: 前提から結論への道筋を辿る語句だけを置く
50
+ - **見出しは主張にする。** 話題名ではなく、聴衆が持ち帰る 1 文。表紙・章扉だけは役割(タイトル・章名)が見出しになる
51
+ - **ほとんどのページに `description` を付ける。** 見出しの下に、そのページが何を示すかを 1 行で。表紙・自己紹介・章扉・一言のページには付けない
52
+ - **結論を文字で繰り返さない。** 主役(コードの実物、図)に語らせ、見てほしい箇所を `focus` で指定する
53
+ - **聴衆が知らない用語は現物で見せる。** 知っているもの(ソースなど)と、その用語の現物を並べる。説明だけで済ませない
54
+ - **仕組みの説明は、後のページで使う前に置く。** 後で「〜に差し込む」と言うなら、その「〜」が何かを先のページで見せておく
55
+
56
+ ## 見せ方の選び方(basic の tags)
57
+
58
+ | 伝えたいこと | tags |
59
+ |---|---|
60
+ | 発表のタイトル / 自己紹介 / 章の区切り | `header` / `profile` / `section-header` |
61
+ | 一言だけ | tags なしで本文 1 行(中央に大きく出る) |
62
+ | 説明と主役(コード・画像)を並べる | tags なし(中身の数で自動配置。2 つなら左右) |
63
+ | 主役を大きく、補助を小さく | `main-right`(主役を最後に書くと右に大きく)/ `main-left`(主役を最初に書くと左に大きく) |
64
+ | 2 つを比べる | `two-column`(`left` / `right` を付けた block を左右に) |
65
+ | 並列の項目 3〜4 つ | `card`(`item` をカードに)/ `columns` |
66
+ | 横に並べたまま 1 つを目立たせる | `columns` + `focus`(主役の列だけ黄金比倍の幅) |
67
+ | 手順・段階 | `flow`(縦)/ `flow` + `direction: row`(横)/ `flow boxed` / `flow framed` / `flow grid` |
68
+ | 数字や固有名詞を大きく | `stat` |
69
+ | 引用 | `quote` |
70
+
71
+ ## コードを載せるとき
72
+
73
+ - **実物を載せる。** コマンドの出力(`javap` など)やライブラリが生成するものは、実際に実行して得た結果を貼る。それらしく作らない
74
+ - **1 行を短くする。** 同じページのコードは同じ文字サイズにそろうので、1 つでも長い行があると全部が小さくなる。目安は、画面の半分の幅で 40 字、3 等分で 30 字。改行位置は変えてよいが、中身は変えない
75
+ - **`check` の warn を見る。** 「下限の 14px まで縮んでいる」「行が折り返している」が出たら、行を短くするか、`main-right` / `columns` + `focus` で主役の幅を広げる
76
+ - **見てほしい行は `focus` で指定する。** 行番号、`"6-8"` の範囲、行に含まれる文字列で書ける
77
+
78
+ ## 図や画像
79
+
80
+ - `public/` に置いて `image` で参照する。外部の画像は URL でもよい
81
+ - 図を SVG で描くときは、テーマの色(primary / accent / ink / muted)を使い、文字は要素のラベルだけにする
82
+ - 頻度や割合を伝えたいときは、個数で描かない(4 台のうち 1 台を赤くすると「1/4」に見える)。繰り返しを並べ、その中の 1 つとして描く
83
+
84
+ ## 見せ方が足りないとき
85
+
86
+ - `src/` に Layout(React コンポーネント)を書き、`definePlugin` で tags に bind して `slide.config.ts` の `plugins` に足す。data の書き方は変わらない
87
+ - `bind` の `description` には、見た目より先に「どういう内容のページで使うか」を書く。schema に出て、エージェントが tags を選ぶ手がかりになる
88
+ - 意図して枠の外へ出す装飾には `aria-hidden="true"` を付ける(`check` の対象から外れる)
89
+ - チャートや three.js など、npm の React コンポーネントもそのまま import して使える。ブラウザで動かす必要があるものは `bind` に `client: true` を付ける
90
+ - 詳しくは https://onfi.github.io/yadeck/guide/custom-template と https://onfi.github.io/yadeck/guide/client
91
+
92
+ ## 発表と公開
93
+
94
+ - `deck.html?mode=presenter` で発表者モード(今と次のページ、ノート、タイマー)。`L` でレーザーポインタ、`B` で暗転
95
+ - 公開先が決まったら `slide.config.ts` の `siteUrl` に書く(canonical と OGP の URL が入る)。説明文を整えたいときは deck の `$meta.description` に書く
96
+ - 公開方法(GitHub Pages / Cloudflare)は https://onfi.github.io/yadeck/guide/deploy
97
+
98
+ ## 更新
99
+
100
+ - YADECK: `npm update @yadeck/slide-core @yadeck/slide-components-basic`
101
+ - skill: `npx skills add onfi/yadeck --skill yadeck -y`(既存の skill を上書きする。一度これで入れた後は `npx skills update yadeck` でもよい)
@@ -119,7 +119,7 @@ what(載せる情報)から考えない。何を伝えたいかが先で、次
119
119
  | 対比 | 主役を 2 つ横に並べ、違う箇所を焦点に | 期待と実際、before / after | `two-column` |
120
120
  | 分割 | 3〜4 を等分に並べる | 選択肢、サービス一覧 | `card` / `columns` |
121
121
  | 全体+拡大 | 全体を小さく、注目部分を大きく | ログの 1 行、図の一部 | (Layout 無し。SVG に描き込む) |
122
- | 主+従 | 主役を大きく、補助の現物や数字を小さく添える | 図+根拠の数字 | tags 無し(2 pane) |
122
+ | 主+従 | 主役を大きく、補助の現物や数字を小さく添える | 図+根拠の数字、コードの変換前後 | `main-right`(主役を最後に書いて右に大きく)/ `main-left`(主役を最初に書いて左に大きく)/ 横に並べたまま主役の列だけ広げるなら `columns` + `focus` |
123
123
  | 段階開示 | 同じ構成を複数ページで少しずつ増やす | 流れを 1 段ずつ | ページを複数書く |
124
124
 
125
125
  - 表紙は「単独 × 一言」(basic では `header`)、章扉も「単独 × 一言」(`section-header`)、まとめは「単独 × 列挙」、プロフィールは「説明+主役 × 現物(写真)」
@@ -157,7 +157,7 @@ note: 原稿「<冒頭数語>」〜「<末尾数語>」(行番号や見出し)
157
157
 
158
158
  1. YAML を書く(書き方は下記)。`note` には原稿の該当箇所をそのまま入れる
159
159
  2. `npx yadeck validate` でフィールドの誤りが無いことを確認する
160
- 3. `npx yadeck check --deck <deck> --slide <N> --png` で、そのページを Chromium で描画して検査する(N は `#s<N>` の数字)
160
+ 3. `npx yadeck check --deck <deck> --slide <N> --png` で、そのページを Chromium で描画して検査する(N は右下のページ番号か、`$id` で付けた名前)
161
161
  - `error`(スライドの外へのはみ出し、枠で切れて見えない文字)は、利用者に見せる前に直す。data で直せなければ Layout の問題として報告する
162
162
  - `warn`(端の余白への食い込み、コードが下限サイズまで縮んでいる、コードの折り返し)は、見せ方の問題として報告に添える
163
163
  - 見た目を目で確かめたいときは、書き出された PNG(`dist/png/<deck>/s09.png`)を読む。全ページを見るなら `npx yadeck png --deck <deck>`。ブラウザ操作のツールでの確認はしない
@@ -181,7 +181,10 @@ note: 原稿「<冒頭数語>」〜「<末尾数語>」(行番号や見出し)
181
181
  - card: # slide の tags は単一キーで書く。値が配列なら items
182
182
  - heading: 見出し
183
183
  - item: { title: 名前, $text: 説明 }
184
- - description: 見出しの下に添える 1 行 # slide のフィールドを書くときは map にして $items を使う
184
+ - $id: page-name # ページの名前(任意)。URL の #page-name、check --slide page-name で指せる
185
+ description: 見出しの下に添える 1 行 # slide のフィールドを書くときは map にして $items を使う
186
+ sources: # 出典(任意、8 件まで)。ページの下端に小さく出る
187
+ - { title: 仕様書の節の名前, url: "https://..." }
185
188
  $items:
186
189
  - heading: 見出し
187
190
  - 本文
@@ -194,6 +197,8 @@ note: 原稿「<冒頭数語>」〜「<末尾数語>」(行番号や見出し)
194
197
  - 単一キーの map `{ K: V }` は `K` を空白区切りで tags にする(`section-header t` のように複数可)
195
198
  - 構造キー(`$tags` `$items` `$text` `$meta` `$version`)はフル記述のときだけ `$` 付きで書く
196
199
  - `public/` に置いたファイルは `./name.ext` で参照する
200
+ - 利用者とページを指し合うときは、ページ番号より `$id` の名前を使う。前にページを足すと番号はずれるが、名前は変わらない。何度も手を入れそうなページには `$id` を付ける
201
+ - 事実(仕様、数値、引用、コマンドの出力)を載せたページには `sources` に出典を書く。公式の一次資料(仕様書、API ドキュメント、公式サイト)を優先し、実在を確かめた URL だけを書く
197
202
  - tags 無し slide の自動レイアウト: テキスト系は全部で 1 pane、`code` / `image` / `video` / `flow` は 1 つずつ 1 pane。1: 全面、2: 左右、3: ト型、4: 十字、5 以上: 左右 2 列。詳細は schema の「tags なし(既定)」の description
198
203
 
199
204
  ## やってはいけないこと
@@ -11,8 +11,8 @@
11
11
  "png": "yadeck png"
12
12
  },
13
13
  "dependencies": {
14
- "@yadeck/slide-components-basic": "^0.1.1",
15
- "@yadeck/slide-core": "^0.1.1",
14
+ "@yadeck/slide-components-basic": "^0.1.2",
15
+ "@yadeck/slide-core": "^0.1.2",
16
16
  "react": "^19.3.0",
17
17
  "react-dom": "^19.3.0",
18
18
  "zod": "^4.6.0"