Writing Style

The conventions every explanation on this site follows. Extracted from edits made to drafted text, so each rule is a correction that was actually needed rather than a preference stated in advance.

このサイトのすべての説明が従う規約です。下書きに対して実際に加えられた修正から抽出しているため、それぞれの規則は、あらかじめ表明された好みではなく、実際に必要だった訂正です。

Punctuation

Do not use em-dashes for asides. Use parentheses for a gloss or an example, a comma for a trailing clause, or a full stop to start a new sentence.

補足に em ダッシュを使わないでください。語句の補足や例には丸括弧を、後続の従属節にはカンマを、それ以外は文を分けて句点を使います。

Not: Colors are generated in OKLCH — lightness, chroma, hue — rather than RGB.
But: Colors are generated in OKLCH (lightness, chroma, hue) rather than RGB.

Not: …not absolute saturations — which is why increasing Most never pushes a color out of gamut.
But: …not absolute saturations, which is why increasing Most never pushes a color out of gamut.

Not: …at a particular lightness — yellows near the top, blues much lower — and the generator finds that lightness.
But: …at a particular lightness: yellows near the top, blues much lower. The generator finds that lightness.

A colon introduces an example or a list. When an aside would make a sentence run long, end the sentence and start another.

コロンは例や列挙を導きます。補足によって文が長くなる場合は、そこで文を終えて次の文を始めます。

A bold label ends with a colon, not a period: **Depth:**, not **Depth.**. In Japanese the colon is full width: 「深度：」.

太字のラベルはピリオドではなくコロンで終えます。`**Depth.**` ではなく `**Depth:**`。日本語では全角のコロンを使います（「**深度：**」）。

Use the serial comma: “depth ordering, sampling, and color selection”.

列挙の最後の項目の前にもカンマを置きます。"depth ordering, sampling, and color selection"。

Sentences

Keep the relative pronoun. Write “colors that sRGB cannot display”, not “colors sRGB cannot display”.

関係代名詞は省略しません。"colors sRGB cannot display" ではなく "colors that sRGB cannot display" と書きます。

Lead with the action rather than the condition around it.

動作を先に置き、その周辺の条件を後に回します。

Not: In HSL, holding saturation and lightness fixed while sweeping hue produces colors of wildly different brightness.
But: In HSL, sweeping the hue while keeping saturation and lightness fixed can produce colors with very different brightness.

Hedge a claim that only holds sometimes. “Can produce” where the outcome depends on which hues are involved; “produces” only where it always does.

条件によっては成り立たない主張には、断定を避けた表現を使います。結果が色相に依存する場合は "can produce"、常にそうなる場合にのみ "produces" を使います。

A labeled item in a list carries one fact. A second sentence adding a secondary fact gets cut, not appended.

ラベル付きの項目が担う事実はひとつです。二次的な事実を加える2文目は、付け足すのではなく削ります。

Cut: Sampling is spaced by arc length rather than by curve parameter, so density stays uniform where control points bunch up.
Kept: Sample count (number of vertices) is derived from measured arc length, not from how many control points the path was authored with.

Words

American spelling throughout: color, toward, behavior.

綴りは一貫してアメリカ式にします。color、toward、behavior。

Plain verbs over dramatic ones. Cut intensifiers that add heat but no information.

大げさな動詞よりも平易な動詞を使います。熱量だけを足して情報を足さない強調語は削ります。

Not: wildly different · yellow leaps out · that is where yellow can be vivid at all
But: very different · yellow pops · that’s the only place yellow can be vivid

Name the noun instead of using an adjective as one: “at that hue’s most saturated point”, not “at that hue’s most saturated”.

形容詞を名詞の代わりに使わず、名詞を明示します。"at that hue's most saturated" ではなく "at that hue's most saturated point"。

Contractions are fine. “That’s the only place” reads better than “that is where”.

短縮形を使って構いません。"that is where" よりも "that's the only place" のほうが読みやすくなります。

Name the standard term instead of deriving it. If a phenomenon has an accepted name, use it and stop; do not reconstruct the mechanism from first principles.

標準的な用語は、導出せずにそのまま使います。現象に定着した名前があるなら、それを使って終わりにします。仕組みを一から組み立て直さないでください。

Not: Two surfaces at the same depth have no defined winner, and the depth test picks one per fragment. The step and the rise remove that question before it can be asked.
But: Z slightly elevates along the stroke to avoid z-fighting.

Drop the article on a noun that names the topic: “Strokes are 2D”, “Sample count is derived”, not “The strokes are 2D”, “The sample count is derived”.

主題を名指しする名詞には冠詞を付けません。"The strokes are 2D" や "The sample count is derived" ではなく、"Strokes are 2D"、"Sample count is derived" と書きます。

Gloss a term with a parenthetical on first use, in English as in Japanese: “sample count (number of vertices)”.

日本語と同様、英語でも初出の用語には丸括弧で補足を添えます。"sample count (number of vertices)"。

Call a set of colors chosen to relate a “scheme”, not a “theme”. “Scheme” is the standard term (monochromatic, analogous); “theme” reads as a visual style.

互いに関係づけて選んだ色の集合は「theme」ではなく「scheme」と呼びます。「scheme」が標準的な用語で（モノクロマティック、アナログなど）、「theme」は視覚的なスタイルの意味に読まれます。

Scope

Describe features of the library. Do not describe the arbitrary decisions of a demo: the shape of its test path, its taper constants, how its colors happen to be picked, or plumbing the reader does not act on. A demo decision is worth a sentence only when the demo would mislead without it.

ライブラリの機能を記述してください。デモの恣意的な決定は記述しません。テスト用パスの形、先細りの係数、色のたまたまの選び方、読者が関与しない内部の配管などです。デモの決定に一文を割く価値があるのは、それがないとデモが誤解を招く場合だけです。

Cut: Each path runs straight for its first third, then wiggles. The amplitude is held at zero and eased in with a smoothstep…
Cut: …the background from the light end, the strokes from the dark end, grouped by hue so two strokes never come back as near-identical shades.
Kept: The sample count is derived from measured arc length, not from how many control points the path was authored with.

The kept example survives because it states what the library does with any path. The cut examples describe one demo’s inputs, which the reader can neither reuse nor act on.

残した例は、ライブラリがどんなパスに対しても行うことを述べているため生き残ります。削った例はひとつのデモへの入力の説明であり、読者はそれを再利用することも、それに基づいて行動することもできません。

Endings

Stop when the fact is stated. Do not append a clause explaining why the fact matters, or restating it in other words.

事実を述べ終えたら止めます。その事実がなぜ重要かを説明する節や、言い換えて繰り返す節を付け足さないでください。

Not: OKLCH is built so a fixed lightness reads as a fixed lightness across every hue, which is what lets a column of the grid hold together as a column.
But: OKLCH is designed so that a fixed lightness reads as a consistent lightness across hues.

That example also shows the rhetorical repetition to avoid — “a fixed lightness reads as a fixed lightness”, “hold together as a column”. Repeating a word for effect reads as a flourish. Vary the second use, or cut the clause.

この例は、避けるべき修辞的な反復も示しています。"a fixed lightness reads as a fixed lightness"、"hold together as a column"。効果を狙った語の反復は、飾りとして読まれます。二度目の語を変えるか、その節を削ってください。

A brief reason for a foundational choice is content, not padding: “OKLCH is one of the most perceptually accurate and computationally performant color models.” The rule above targets restating why an already-stated fact matters, not justifying a design decision.

基礎となる選択に対する短い理由づけは、飾りではなく情報です。「OKLCHは、知覚的に正確で計算上も効率的なカラーモデルのひとつです」。上の規則が禁じるのは、すでに述べた事実の重要性を言い換えることであって、設計上の判断を裏づけることではありません。

Openings

Open a page with a plain description of what the thing is. Not an aphorism, not a hook, not a first-person musing.

ページの冒頭は、それが何であるかの平易な説明にします。警句でも、引きでも、一人称の独白でもありません。

Not: Before deciding what a mark looks like, decide what colors exist.
But: A reusable palette class that distributes colors using the OKLCH model

Monologues

The monologue at the top of a page is the working-log voice, not the documentation voice. It may use the first person and a reflective tone (the exception to the “no first-person musing” rule, which governs the prose body). Each monologue carries a Japanese counterpart in a nested <div class="jp">, following the Geom project’s style.

ページ冒頭の`monologue`は、ドキュメントの声ではなく制作ログの声です。一人称や内省的な調子を使って構いません（本文に対する「一人称の独白を避ける」規則の例外です）。各モノローグには、Geomプロジェクトのスタイルにならって、入れ子の`

`で対応する日本語を添えます。

The opening monologue says what we do on the page, in the first person: it opens with “On this page, we …” and a verb that names the action (build, explore, study, wire, replay). Not a bare description of the thing, and not its inputs or mechanics, which belong in the prose below.

冒頭のモノローグは、そのページで何をするのかを一人称で述べます。「On this page, we …」で始め、行為を名指す動詞（build、explore、study、wire、replay など）を続けます。もの自体の素の説明でも、入力や仕組みでもありません。それらは下の本文に置きます。

Not: A stroke class that turns a path and a width into drawable geometry
But: On this page, we build the stroke class that turns a path and a width into drawable geometry, and the renderers that shade it.

The Japanese follows the Geom monologue register: written from the meaning, reflective, and free to break into short sentences (けれど, そこで) rather than tracking the English clause for clause.

日本語はGeomのモノローグの語り口にならいます。意味から書き起こし、内省的で、英語の節を逐一なぞるのではなく短い文に区切って構いません（けれど、そこで）。

Intros

An intro may motivate the approach by contrast, naming the naive option and what the library does instead (“Rather than relying on randomly chosen colors, we develop several strategies…”). Name the sibling project (Geom) when the logic carries over from it.

導入は、素朴な選択肢と、その代わりにライブラリが何をするのかを対比させて動機づけて構いません（「ランダムに選んだ色に頼るのではなく、いくつかの戦略を構築します」）。ロジックがGeomプロジェクトから引き継がれている場合は、その名前に触れます。

Headings

A short noun phrase naming the topic. Not a question, not a clause, not an evocative phrase.

見出しは、主題を示す短い名詞句にします。疑問文でも、節でも、含みを持たせた表現でもありません。

Name the concept the reader recognizes, not the internal mechanism: “Representative colors”, not “Representative lightness”.

読者が認識する概念を名指し、内部の仕組みは名指しません。「Representative lightness」ではなく「Representative colors」。

Not: How the palette is built · Where the lightness steps land
But: Color Selection · Distribution of the steps

Japanese

Every English paragraph is followed by its Japanese counterpart in a <div class="jp">. The Japanese mirrors the English structure, parentheses included.

英語の段落には必ず、対応する日本語を `

` で続けます。日本語は括弧の使い方を含めて英語の構造を反映させます。

Use full-width parentheses （） for asides, with the plain form inside: 見かけの明るさが大きく変わってしまいます（黄色は飛び出し、青は沈む）。

補足には全角括弧（）を使い、その中は常体にします。

Write the Japanese from the meaning, not as a gloss of the English sentence. When the English rests on a copula or a noun phrase, pick the verb that says what happens.

日本語は、英文の逐語的な写しではなく、意味から書き起こします。英語がコピュラや名詞句で済ませている場合は、何が起こるのかを示す動詞を選びます。

Not: すべての色が基準の色相です。最初の色はその色相が最も鮮やかになる点に置かれ、残りはその固定された最初の色が許すかぎり均等に明度の範囲を分割します。彩度はそれぞれの明度で使える最大値です。
But: すべての色は基準の色相に揃えられます。最初の色は、その色相が最も鮮やかになる点に配置され、残りの色は、その最初の色が許す範囲で明度の幅を均等に分割して配置します。彩度は、各明度で取りうる最大値です。

That example carries several rules. Put a 読点 after a topic phrase (「最初の色は、」) when the sentence continues at length. Drop modifiers the English needed but the Japanese context already carries (「その固定された最初の色」 becomes 「その最初の色」). Choose the verb that names the operation rather than the generic verb the English word suggests (置く becomes 配置する, 使える becomes 取りうる), and complete the action the English leaves implied (分割します becomes 分割して配置します). Prefer 各明度 over それぞれの明度.

この例はいくつかの規則を含んでいます。文が長く続くときは、主題の句のあとに読点を打ちます（「最初の色は、」）。英語には必要でも、日本語では文脈が担っている修飾語は落とします（「その固定された最初の色」は「その最初の色」に）。英単語が示す一般的な動詞ではなく、その操作を名指す動詞を選び（置く→配置する、使える→取りうる）、英語が言外に済ませている動作は言い切ります（分割します→分割して配置します）。「それぞれの明度」よりも「各明度」を使います。

Prefer the active or potential form over the passive when the reader acts. The passive is fine, and often natural, when describing how the generated result is arranged.

読者が操作する場面では、受身よりも能動形・可能形を優先します。生成された結果の配置を述べる場面では、受身のままで構いません（そのほうが自然なことも多くあります）。

Not: スウォッチをクリックすると16進数の値がコピーされます。
But: スウォッチをクリックすると16進数（hex）をコピーできます。

Gloss a technical term on first use: 16進数（hex）.

専門用語には初出時に原語を添えます。16進数（hex）。

For a color scheme, the Japanese is 配色, not テーマ.

カラースキームの日本語は、テーマではなく配色です。

Keep proper names and UI labels in English inside the Japanese text, not katakana: **Monochrome：**, **Vivid & dark：**, not **モノクローム：**, **ビビッド＆ダーク：**. (This applies to the names; a general concept like 配色 stays Japanese.)

固有名やUIのラベルは、日本語のなかでもカタカナにせず英語のまま置きます。`**モノクローム：**`や`**ビビッド＆ダーク：**`ではなく`**Monochrome：**`、`**Vivid & dark：**`。（対象は名前であって、配色のような一般概念は日本語のままにします。）

No spaces around inline markup in Japanese text: Chromaの<strong>Most</strong>と<strong>Least</strong>は — not Chromaの <strong>Most</strong> と.

日本語のなかのインライン要素の前後に空白を入れません。`Chromaの Most と` ではなく `ChromaのMostとLeastは`。