# スタイルガイド
このページは **リファレンスであると同時に、その証明** でもあります――以下の
すべての要素は Ovellum のデフォルトテンプレートでレンダリングされた本物の
Markdown なので、ここで目にするものはそのままあなた自身のページに反映されます。
タイプスケール、垂直リズム、カラーシステム、そして書ける各コンテンツ要素を
ここで説明します。
読みながら、トップバーの **外観コントロール** を試してみてください。モード
（自動 / ライト / ダーク）を切り替えたり、テーマを選んだり、色を設定したり、
**テキストサイズ** を上げたり、**フォント**（Default / Serif / Inter / Geist）を
変えたりできます。このページのすべてが同じデザイントークンで駆動されているため、
リアルタイムで再着色・再フローします。
## タイポグラフィ
テキストと見出しは、デフォルトで **システムのサンセリフ** スタックを使います――
初回描画が即座で、ウェブフォントの読み込み待ちがありません。読者は外観
コントロールの **フォント** ピッカーから **Serif**、**Inter**、**Geist** に
切り替えられ（Inter と Geist はテンプレートに同梱され、選択されたときのみ
読み込まれます）、**テキストサイズ** を上下に調整できます。書体とサイズは
*読者* の選択ですが、以下のスケール、リズム、カラーは Ovellum 出荷時の
デフォルトであり、どのテンプレートにも適用されます。
本文は **`76ch` の measure** の内側で **`1.55` の行間** で組まれます――読書用の
段は約 76 文字/行に制限されており、長い散文でも快適さが保たれる帯域です。
見出しは **`1.2` の行間** に締まり、わずかな負の字間によって、間延びした語の
並びではなく一つのまとまりとして読めます。
### タイプスケール
サイズは **モジュラースケール** から導かれます。一つの基準サイズに、各ステップで
固定の比率を掛けていきます。Ovellum は、小さな画面の約 15px から広い画面の
16px まで成長する流動的な基準（単一の `clamp()`――ブレークポイントなし）の上で
**長三度（1.25）** を使います。各見出しはステップに対応するため、階層は手作業で
選んだものではなく数学的です。
| ステップ | 基準からの比率 | 使用箇所 |
| --------------- | --------------- | -------------- |
| `--font-size-4` | 1.25⁴（≈ 2.44×） | `h1` |
| `--font-size-3` | 1.25³（≈ 1.95×） | `h2` |
| `--font-size-2` | 1.25²（≈ 1.56×） | `h3` |
| `--font-size-1` | 1.25¹（1.25×） | `h4`、lead |
| `--font-size-0` | 1×（基準） | 本文、`p`、`li`|
各ステップが `calc(previous × var(--ratio))` であるため、一つの `--ratio`
トークンを変えるだけで、階層全体が比例して再フローします。
### 見出し
6 つのレベルを、実際のサイズでレンダリングしたものです。
# 見出しレベル 1
## 見出しレベル 2
### 見出しレベル 3
#### 見出しレベル 4
##### 見出しレベル 5
###### 見出しレベル 6
各見出しには安定した `id` とホバー時のアンカー（`#`）が付くため、どのセクションにも
直接リンクできます。また `h2`/`h3` は右側の「このページの内容」リストに
集約されます。
## 垂直リズム
スペーシングは場当たり的ではなく、**流動的なスペーススケール**
（`--space-3xs` から `--space-3xl` まで）です。各ステップはビューポートとともに
緩やかに成長する `clamp()` です。ブロック要素は一つのルールを共有します――
**上マージンなし、下に一貫した間隔**――そのため、リズムはページを下るにつれて
予測可能に積み重なります。見出しはより大きな導入の間隔を *上* に追加します
（`h2` は手前に十分な間隔、後ろにわずかな間隔を取って新しいセクションを開きます）。
これが、見出しを、それが導く本文に結びついているように感じさせる仕組みです。
## 段落とインラインテキスト
段落が基準を定めます。この文は、**強調のための太字**、*ストレスのための斜体*、
そして識別子のための `inline code` を示しています――コードはかすかな色味と
等幅書体を得るため、`OvellumUserConfig` のようなシンボルが散文と取り違えられる
ことはありません。[設定リファレンス](/ja/docs/reference/config/) のような
リンクはアクセントカラーと、ベースラインからオフセットした細い下線を帯び、
[ホバーで色味が変わります](/ja/docs/reference/config/)。撤回のために
~~取り消し線~~ でテキストに線を引くこともできます。
> 引用は、先頭の縁に 1 本のルールを引き、文字を控えめにして、わずかに字下げ
> されます――箱で囲むのではなく、静かに。傍注や引用句に使い、強調には使わない
> でください（それは太字の役割です）。
### コールアウト
GitHub スタイルのアラート引用は、色付きのコールアウトパネルになります。
> [!NOTE]
> 周囲の散文を補う、役立つ文脈。
> [!TIP]
> 物事を行うための近道や、より良い方法。
> [!IMPORTANT]
> 読者が本当に見逃すべきでないこと。
> [!WARNING]
> 鋭い角――慎重に進めてください。
> [!CAUTION]
> データ損失や、元に戻しづらい操作のリスク。
### コンポーネントディレクティブ
`:::` ディレクティブ（[コンポーネントガイド](/ja/docs/guides/components/)を参照）の
ライブレンダリングです。カスタムラベル付きのコールアウト:
:::tip{title="ショートカット"}
同じパネルは `:::note` / `:::warning` ディレクティブからも使えます。
:::
ステップ:
::::steps
:::step{title="インストール"}
`npm install -D ovellum`
:::
:::step{title="初期化"}
`npx ovellum init` を実行します。
:::
::::
カード:
::::cards
:::card{title="手動モード" href="/ja/docs/guides/manual-mode/"}
Markdown から静的サイトを構築します。
:::
:::card{title="コンポーネント" href="/ja/docs/guides/components/"}
ディレクティブの完全なリファレンス。
:::
::::
タブ:
::::tabs
:::tab{label="npm"}
`npm install -D ovellum`
:::
:::tab{label="pnpm"}
`pnpm add -D ovellum`
:::
::::
コードグループ:
:::code-group
```bash
npm install -D ovellum
```
```bash title="pnpm"
pnpm add -D ovellum
```
:::
図（Mermaid — オンデマンドで読み込み）:
```mermaid
graph LR
Source --> Parser --> Generator --> Merger --> Docs
```
## リスト
順序なしリストは、控えめな色の静かなマーカーを使い、間隔を詰めて入れ子になる
ため、深さが階層として読めます。
- 1 行か 2 行に収めた最初の項目。
- 入れ子の詳細を伴う 2 番目の項目:
- 入れ子のポイント。
- インデントのステップを示すための、もう一つ。
- さらに 1 段深いもの。
- 最後の項目。
順序付きリストも同じリズムを帯びます。
1. Markdown でページを書く。
2. `ovellum build` を実行する。
3. `dist/` の出力を任意の静的ホスティングにデプロイする。
タスクリストはチェックボックスをレンダリングします。
- [x] タイポグラフィスケール
- [x] カラーシステム
- [ ] あなたの次のページ
## 脚注
脚注の参照は小さな上付き文字として置かれ[^sg-note]、脚注へリンクし、脚注からは元へ
戻れます。参照は出現順に番号が振られ、脚注は本文より 1 段小さい、うっすらと色のついた
パネルにページ末尾でまとめられます。[^sg-second]
[^sg-note]: 脚注自体もインライン Markdown を取れます — `code`、*強調*、さらには
[リンク](/docs/reference/config/)も。
[^sg-second]: リストの番号付けとパネルのリズムを示すための 2 つ目の脚注です。
## コード
インラインコードは `const x = 1` のように読めます。フェンスで囲まれたブロックは、
CSS 変数を介して出力されるライト/ダークのデュアルテーマで Shiki により
ハイライトされます――そのため色は外観モードとともに切り替わり、ランタイムの
コストはゼロです――言語のラベルとコピーボタンが付きます。
```typescript
import { defineConfig } from 'ovellum';
export default defineConfig({
mode: 'manual',
input: 'content',
output: 'dist',
site: {
title: 'My Docs',
palette: 'default',
},
});
```
```bash
ovellum build
```
## テーブル
テーブルはエディトリアルカーム――横罫のみで、格子線もヘッダーの塗りもありません。
ヘッダーは太さとより厚い下罫で読み取れます。列より幅の広いテーブルは、レイアウトを
崩すのではなく横スクロールします。
| 要素 | トークン | 備考 |
| ----------- | ---------------- | ------------------------------------- |
| 本文 | `--font-size-0` | 流動的な 15→16px の基準 |
| Measure | `--content-max` | `76ch` の読書用段 |
| 本文リズム | `--leading-normal` | `1.55` の行間 |
| 見出し | `--leading-tight` | `1.2` の行間、負の字間 |
## 画像
画像は段の幅にスケールし、アスペクト比を保ち、他のメディアと同じ角丸を帯びます。
これはページの Markdown ファイルの隣（`styleguide-sample.jpg`）に置かれ、
ルート絶対パスで参照されています――[アセットとダウンロード](/ja/docs/guides/assets/)
ガイドが、ページ固有の画像に推奨するパターンです。
## 動画
YouTube や Vimeo から埋め込みコードをそのまま貼り付けてください――「共有 →
埋め込む」をそのままコピーするだけ――それで動きます。Ovellum は、それらの既知の
動画ホストからの `
上の YouTube 動画埋め込みのコードがこれです――YouTube が **共有 → 埋め込む** で
渡してくる正確なスニペットを、そのまま Markdown に落とし込んだものです。
```html
```
ほかに何もする必要はありません――固定の `width`/`height` と `frameborder` は
無害なまま付いてきます。Ovellum のレスポンシブラッパーがピクセル寸法を上書きし、
`loading="lazy"` と厳格なリファラーポリシーが自動的に適用されます。
（YouTube のプライバシー保護ホストには `https://www.youtube-nocookie.com/embed/…`
に差し替えてください。）セルフホストのクリップには、ネイティブの `