mdmark

HTML の書き方

AI が HTML を作るときの書き方の決まり

図・チャートなど見た目のあるものを HTML で作るときに従う決まり。 フロー図・シーケンス図・グラフ・操作できる部品は HTML を書かず、図を描く の部品の定義で描く。

使いどころ

描くもの	書き方
文章・表・手順・リスト	Markdown
フロー図・シーケンス図・グラフ・操作できる部品	部品の定義（JSON）
部品で描けない図・チャートなど見た目のあるもの	HTML

決まり

項目	決まり
自己完結	外のファイル・CDN・フォントを読まない。図は 1 つの HTML に収める
色と文字	色・書体・角丸は --mdmark- の CSS 変数で書き、色の値を直に書かない。変数はライトとダークで切り替わる。変数の一覧は テーマの CSS 変数
色だけで分けない	意味の違いは、色に加えて形・模様・文字・アイコンでも示し、凡例に全て書く
題と凡例	図ごとに題名・範囲・更新日と凡例を付ける
読み上げ	図に名前を付け、操作できる要素には読み上げの名前を付ける。アイコンだけのボタンは aria-label を付ける
キーボード	操作は全てキーボードでもできる。ドラッグだけの操作にしない
ツールチップ	ホバーとフォーカスの両方で出し、Esc で消し、上に乗っても消えない。理解に必須のことは入れない
拡大・縮小	ボタンとキーで行う。ホイールは普通のスクロールに使う
文字	文字の上では選べる。ドラッグで図を動かすときは、文字の上を除く
スクリプト	文書に書いた <script> は動かない。動きが要る部品は、使う側のページに載せて動かす

確かめる

置いたら、動かして、スクリーンショットを撮って見る。 手順は 描いた図を確かめる。

mdmark の文書に書いた HTML で残るもの

文書に書いた HTML は、描く前に許した要素・属性・URL だけを残す。

項目	残るもの
要素	標準の要素と img・del・details・summary。文書に書いた input は、チェックボックスで操作できない形に直す。svg・button・output は残さない
class	language-*・mdmark-align-*・task-list-item・mdmark-embed だけ
属性	style・id・data-*・on で始まる属性は残さない
URL	href と src は http・https・mailto と相対 URL だけ

見た目を自分で作る HTML は、使う側のページに載せるか、画像にして置く。

埋め込んだ HTML で残るもの

<!-- html --> の範囲に置いた html のコードブロックの HTML は、上の文書に書いた HTML と同じ許可の検査を通してから、その場に描く。 書き方は コードブロックのHTMLを描く。

項目	決まり
スクリプト・イベントの属性	script 要素・on で始まる属性・javascript: の URL は落ち、動かない。動くのは mdmark の部品だけ
button	残る。type="button" に固定し、form で始まる属性は落とす。押しても何も起きない
style	下の宣言だけが残る
data-hint	任意の要素に書け、値の文がツールチップで出る。値は Markdown として読まず、文字として出す
図の部品	<mdmark-flow>・<mdmark-sequence>・<mdmark-chart>・<mdmark-param> の中の JSON を、図の部品の定義として描く。要素の属性は読まない
id・data-*（data-hint を除く）	残さない

style の宣言は、次のものだけが残る。

項目	宣言
残す宣言	display・flex で始まるもの・align-items・align-self・justify-content・grid で始まるもの・gap・row-gap・column-gap・margin で始まるもの・padding で始まるもの・border で始まるもの・width・max-width・min-width・height・color・background-color・font-size・font-weight・text-align
落とす値	url( を含む値・単位 vw・vh を含む値・position・負の margin・padding

幅が本文の列より広い HTML は、描いた枠の中で横にスクロールする。