ChromeのPDFでグラデーションが黒くなる原因｜var()を色の直書きに変えて直した実録【2026年】

HTMLをChromeでPDFにするとマーカー風のグラデーションが黒い帯になるときは、linear-gradient() の色に var() を使っていないかを確かめます。当社では2026年8月6日、色を直書きに変えると直りました。画面では再現しないため、PDFを画像にして確かめる手順も書きます。

ChromeのPDFでグラデーションが黒くなる原因：色の指定に var() を使っていた

当社で起きた症状は、次のとおりです。

• 黄色いマーカー（文字の下半分に引く、下線風のハイライト）が、PDFでは真っ黒な帯になる。文字が塗りつぶされて読めない
• ブラウザの表示は正常。Chromeの印刷プレビューも正常
• できあがったPDFを、macOSのプレビューで開いたときだけ黒い

黒くなったマーカーは、次のCSSで書いていました。

/* 黒い帯になった書き方：グラデーションの色にCSS変数を使っている */
.hl{ background: linear-gradient(transparent 58%, var(--mark) 58%); }

linear-gradient() とは、2色以上の色が直線に沿って変わっていく画像を作るCSSの関数のことです。MDN（Web技術の標準的なリファレンス）によると、2つの色の境目（カラーストップ）を同じ位置に置くと、色はなだらかに変わらず、はっきりした線で切り替わります。上の書き方は、この性質を使って「上の58%は透明、そこから下は黄色」というマーカーを作るものです。

CSS変数（カスタムプロパティ）とは、--mark のように名前を付けて値を登録し、var(--mark) で呼び出して使い回すCSSの仕組みのことです。色を1か所で管理できるので、資料全体の色をそろえるときによく使います。

ヘッドレスモードとは、画面を出さずにChromeを動かす方法のことです。Chrome公式のドキュメントは、見えるUIなしで、人が操作しない環境でブラウザを動かせる、と説明しています。当社はこのモードの --print-to-pdf で、HTMLをPDFにしています。

公式で確かめられたこと・確かめられなかったこと

2026年10月14日時点で、MDNの linear-gradient() のページと、CSS変数のページを確認しました。どちらにも、PDFにしたときにグラデーションの中の var() が黒くなる、という記載はありません。Chromeのヘッドレスモードの公式ページにも、CSS変数やグラデーションについての記載はありませんでした。

つまり、この不具合は公式に説明がある現象ではありません。以下は、当社の環境での実測です。

当社の実測で分かったこと

transparent を残したまま、色を直書きにした2行目が正常でした（境目の位置も58%から55%に少し変えていますが、当社の記録では、直書きの色なら正常に出ると実測で確かめています）。原因は transparent ではなく、色の指定に var() を使っていたことだと判断しています。

当社の記録では、この現象を「ヘッドレスのPDF出力が、グラデーションの中の var() を解決できず、黒になっている」と読み取っています。ただし、これは結果からの読み取りです。Chrome側の問題なのか、PDFを表示する側との組み合わせで起きるのかまでは、切り分けていません。Chromeのバージョンごとの違いも、記録にありません。

Chromeでクリックすると縦線のカーソルが出る原因のときと同じで、「どの条件のときだけ起きるか」を先に押さえると、直す場所が決まります。

PDFでグラデーションが黒くなるときの対処手順：色を直書きにする

1. HTMLとCSSの中から、グラデーションを探す。 gradient で検索します。
2. その中に var( が入っている行を見つける。 見るのは、グラデーションのかっこの中だけです。color: var(--text) のように、グラデーションの外で使っている var() は、当社の資料では問題になっていません。
3. 色を直書きに変える。 var(--mark) を、#FDF6A3 のような色の値そのものに置き換えます。

   /* 正常だった書き方：色を直書きにする */
   .hl{ background: linear-gradient(transparent 55%, #FDF6A3 55%); }

1. グラデーションである必要がなければ、ベタ塗りに変える。 当社は最終的にこちらを選びました。

   /* より安全な書き方：グラデーションを使わない */
   .hl{ background-color:#FFF100; font-weight:800; padding:0 3px; border-radius:2px; }

1. PDFを作り直す。 PDFを直接編集せず、HTMLを直してからPDFにし直します。
2. できあがったPDFを画像にして、目で見る。 手順は後の章に書きます。Chromeの画面では確かめられません。

2つの直し方の違いは、次のとおりです。

MDNによると、linear-gradient() が作るのは画像の一種です。そのため background-color には書けません。ベタ塗りに変えるときは、プロパティごと background-color に書き換えます。

裏方で実際に起きた例：2026年8月6日、提案書のマーカーが黒い帯になった

ここからは、僕の会社（株式会社UrakaTA）の運用記録からの転記です。お客さん向けの資料なので、どの資料かが分かる情報は伏せています。

当社は、提案書をHTMLで組み、ChromeのヘッドレスモードでPDFにしています。直すときは、HTMLを書き換えてPDFを作り直します。Claude Codeに任せている制作の仕事の1つで、全体像はClaude Codeでできること｜非エンジニアの活用事例に書きました。

2026年8月6日、ある提案書の制作中に、できあがったPDFのマーカーが真っ黒になっていることに気づきました。強調したい一文に黄色いマーカーを引いたはずが、その一文だけが黒く塗りつぶされて読めません。いちばん読んでほしい所が、いちばん読めなくなっていました。

やっかいだったのは、HTMLをブラウザで開いても、Chromeの印刷プレビューで見ても、正常だったことです。記録には、PDFを画像にする一般的な方法でも再現しなかった、とあります。黒く見えたのは、PDFをmacOSのプレビューで開いたときだけでした。

切り分けは、次の順で進めました。

1. transparent を疑う。→ 残したままでも、色を直書きにすれば正常。原因ではなかった
2. 色を var(--mark) から直書きに変える。→ 正常
3. グラデーションをやめてベタ塗りにする。→ 正常

同じ日に、ほかの資料も調べました。結果は書き方で分かれました。

直書きの資料が正常だったのは、この不具合を知って避けていたからではありません。当時の記録に、そうしたルールはありませんでした。気づかずにCSS変数の版を出していたら、マーカーが黒塗りの提案書をお客さんに渡すところでした。

気づいてから直し終えるまでにかかった時間は、記録に残していないので書きません。

黒い帯を納品前に見つける検査：PDFを1ページずつ画像にして見る

この不具合は、Chromeの画面をいくら見ても見つかりません。当社は、PDFにした後のファイルを、macOSの描画の仕組み（プレビューと同じもの）で画像にして確かめています。使うのは、PDFを加工する qpdf と、macOSの画像変換コマンド sips です。

# 1. PDFを作る
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless --disable-gpu \
  --print-to-pdf="out.pdf" "in.html"

# 2. 確かめたいページ（例：4ページ目）だけを切り出す
qpdf out.pdf --pages . 4-4 -- /tmp/p4.pdf

# 3. 切り出したページをPNGにして、目で見る
sips -s format png -Z 1400 /tmp/p4.pdf --out /tmp/p4.png

qpdf の公式ドキュメントによると、--pages の . は元のPDF（ここでは out.pdf）を指し、4-4 は4ページ目から4ページ目まで、つまり4ページ目だけを意味します。先にページを切り出すのは、当社の記録では sips が複数ページのPDFの1ページ目しか画像にしないためです。

当社の実際のコマンドには、PDFのヘッダーとフッターを消す指定も付けています。ただ、Chromeの公式ページでその指定を確かめられなかったため、上の例からは外しました。--disable-gpu は、Chrome公式の記事の例にある指定です。

この件から、次の3つを運用ルールにしました。

• PDFにする資料では、グラデーションの色にCSS変数を使わない。 ブラウザで見せるだけのLPは対象外です。
• マーカー・グラデーション・影を使ったページは、最低1枚を画像にして見る。 納品前には、装飾のあるページを2〜3枚抜き取って確かめます。
• 直すのはHTML。PDFは作り直す。 PDFを直接編集すると、次に作り直したときに同じ不具合が戻ります。

「画面で正常に見えた」を合格にしない、という考え方は、LPの検品でも同じです。AI導入の失敗事例7つに、目視で漏れた表示崩れを機械の検査で拾った例を書いています。

業務でHTMLからPDFの資料を作るときの注意

読み手が開く方法で確かめる。 当社で黒く見えたのは、macOSのプレビューで開いたときです。お客さんがどのアプリでPDFを開くかは、こちらでは選べません。当社が確かめたのはmacOSだけで、Windowsやスマートフォンでの見え方は記録にありません。

AIに作らせた資料ほど、検査を手順に入れる。 HTMLもCSSも、AIが書けば見た目は整います。ただ、AIが確かめるのもブラウザの表示です。「PDFにした後を画像にして見る」までを作業の手順に書いておかないと、同じ見落としが起きます。当社は、検査の手順をAIが毎回読む社内ルールに入れました。

黒くつぶれる原因は、ほかにもある。 同じ日に、別の黒つぶれも見つけています。番号を丸で囲むために .num b と書いたCSSが、本文の中の太字（<b>）まで黒い丸にしていました。こちらはPDF出力ではなく、セレクタの書き方の問題です。.num > b と、直下の要素だけに効く書き方に変えて直しました。黒くなったら、グラデーションと決めつけずに、どの指定が効いているかを先に見ます。

雛形を1つにそろえる。 資料ごとに雛形が違うと、同じ不具合が一部の資料にだけ残ります。当社は、正常に出た資料を参照用の実装として記録に残し、新しい資料を作るときの元にしています。

この記事にあるのは、当社の1つの環境（macOSとChromeのヘッドレスモード）での実測です。すべての環境で同じ結果になるとは限りません。「HTMLで作った資料がPDFでだけ崩れる」「AIで資料を作る流れに検品を組み込みたい」というときは、下のフォームからご相談ください。