CSS 的 text-shadow 宣告是一行帶有四個值的程式碼 —— 水平偏移、垂直偏移、模糊半徑和顏度 —— 而最省事的撰寫方式，就是一個能預覽、且複製到剪貼簿的字串與預覽完全一致的產生器。一個文字陰影產生器 API 的替代方案，回答了許多開發者私下會問的問題：為了產生一行 CSS，我真的需要一個 HTTP 端點、一個 SDK 金鑰，以及一套版本管理政策嗎？對於一次性的設計調整、行銷頁面，以及小型元件的編修，答案是否定的。一個在本機、只在瀏覽器中執行、會自行驗證輸入、且輸出與顯示的值相同的工具，速度更快、稽核更容易、而且不可能因為過時的用戶端函式庫而誤用。這就是文字陰影產生器 API 替代方案的實務樣貌：有限的輸入、完全相同的預覽、可複製的輸出，以及無需上傳。
當陰影是在伺服器端渲染、預設值必須跨裝置同步、或需要在迴圈中產生大量變化時，由 API 驅動的產生器仍有其用武之地。但當目標是在真實的字型、真實的背景、真實的元件中測試單一陰影時，它們就選錯工具了。本機的做法同時也消除了整合時一整類的臭蟲 —— 只要視覺樣本與匯出的 CSS 開始出現落差，這類問題就會冒出來；這種瑕疵在舊式產生器中很常見，它們透過一條程式路徑組成預覽，卻透過另一條程式路徑產生剪貼簿字串。
為什麼對單一陰影來說，API 來回呼叫是錯誤的形式
text-shadow 屬性是一個基本元素。依據 W3C CSS Text Decoration 規範 與 MDN text-shadow 參考文件，其語法是以逗號分隔的陰影圖層清單，每個圖層接受兩個長度作為偏移、可選的第三個長度作為模糊，以及一個顏度。這就是整個問題領域。把它包進 API 意味著要付出網路延遲、驗證交握和 SDK 版本漂移的成本，才能換回瀏覽器本來就知道如何產生的同一個字串。
此外還有值得點出的資安與隱私面向。API 呼叫會洩露正在進行 UI 設計的事實、在傳輸過程中暴露範例文字，並將設計迭代綁定到服務的可用性。本機產生器則反轉了這個關係：相同的值在目前的分頁中處理、永不上傳，即使在網路關閉的情況下也能產生輸出。對於設計權杖、無障礙稽核和 CI 快照而言，一個「永遠顯示將複製的內容」的產生器所提供的可稽核性，是比請求與回應式來回呼叫更強的保證。
從請求到宣告：本機產生器的運作方式
實作方法刻意保持精簡。工具會驗證預覽文字、有限且帶正負號的偏移、非負的模糊，以及三個六位數的十六進制顏度。從這些經過驗證的輸入，它會剛好序列化出一個 text-shadow 圖層，並將該精確的值套用於畫面上的預覽。共用的計算避免了舊式產生器常見的一種瑕疵 —— 視覺樣本與剪貼簿輸出因為透過不同的程式路徑計算而產生落差。
這個共用的單一值是核心的保證。如果某個陰影在預覽中可見，那麼複製到剪貼簿的 CSS 字串就會產生相同的像素。產生該字串的同一份輸入合約也會渲染預覽，因此不會有第二步的轉換 —— 在那一步中，數字可能被四捨五入、單位可能被加上、或顏度可能被改寫。
精簡的範疇也讓輸出易於檢視。單一行陰影夠小，足以進行 diff、貼進設計權杖的 pull request，並在程式碼審查中大聲讀出來。多圖層堆疊雖然常感覺很強大，卻往往會讓字形變得混濁、產生動畫的繪製成本，並在小字級時通過不了無障礙檢查。對於一個易讀的陰影來說，一個圖層才是正確的答案。
四個步驟建立一個易讀的 text-shadow
- 輸入簡短的預覽文字。輸入一個簡短、類似最終標題或標籤的字串 —— 例如你打算實際上線的那一兩個單字。工具會限制預覽長度以保持樣本的精簡與流暢，因此非常長的字串會被截斷，而非放任破壞版面。
- 調整水平與垂直偏移以及模糊半徑。依序使用滑桿或輸入框設定水平偏移、垂直偏移，再設定模糊。正的水平值將陰影向右移，負值向左移；正的垂直值將陰影向下移，負值向上移。依 CSS 語法，模糊不能為負，因此下限為零，較大的數值則會擴散出較柔和的輪廓。
- 選擇陰影顏度、文字顏度與背景顏度。三個顏度都請挑選完整的六位數十六進制值。陰影顏度就是會被偏移和模糊的那一層；文字顏度與背景顏度則為陰影設定其周圍的可讀性框架。請於所選背景上觀察預覽 —— 同一個陰影在平面上可能看起來清晰，在飽和的背景上卻可能難以辨識。
- 複製宣告並在你的真實元件中驗證。將 CSS Text Shadow Generator 產生的那一行複製到實際的樣式表中，然後用真實的字型、粗細、字級，以及文字在正式環境中會跨越的所有表面進行測試。請於網頁字型載入完成後再次檢查，因為 fallback 的字型度量與最終字形會改變任何陰影的視覺邊緣、間距與視覺重量。
工具接受與不接受的精確輸入
以下的合約就是完整的輸入介面。任何超出範圍的內容會被拒絕而非默默強制轉型，這正是讓預覽保持誠實的原因。
| 輸入 | 接受的範圍或格式 | 無效輸入時的行為 |
|---|---|---|
| 預覽文字 | 類似最終標籤的簡短字串；長度受到限制 | 空輸入會被拒絕 |
| 水平偏移 | −100 到 100 px，限整數或有限小數 | 空值或非有限值會被拒絕，不會被視為零 |
| 垂直偏移 | −100 到 100 px，限整數或有限小數 | 空值或非有限值會被拒絕，不會被視為零 |
| 模糊半徑 | 0 到 100 px，非負 | 負值、空值或非有限值會被拒絕 |
| 陰影顏度 | 六位數十六進制（例如 #1a1a1a） | 不接受簡寫、具名顏度或 rgba 輸入 |
| 文字顏度 | 六位數十六進制 | 與陰影顏度規則相同 |
| 背景顏度 | 六位數十六進制 | 與陰影顏度規則相同 |
請注意，模糊半徑是唯一嚴格非負的欄位。偏移可以是負的，因為 CSS 語法本就允許，而工具反映了這個限制，並未自訂規則。六位數的十六進制格式同樣是刻意為之 —— 它迴避了簡寫展開、alpha 色頻位置，以及跨瀏覽器具名顏度匹配所帶來的歧義。
對於跨 CSS 家族比較陰影效果的讀者而言，box-shadow 屬性的參數與 text-shadow 有重疊，但前者作用在矩形的邊框方塊上，而非字形邊緣。Box Shadow Generator cheat sheet 帶你走過方塊相同的偏移、模糊與擴散語言，當兩種效果同時存在於同一個設計系統中時，是實用的交叉參照。
同一個陰影，可讀性卻天差地別
同一行宣告在一個表面上可能通過無障礙稽核，在另一個表面上卻可能失敗。陰影、文字與背景顏度之所以是必要輸入，正是因為同一組偏移與模糊在淺色、深色、飽和或帶圖案的表面上讀起來效果不同。請把下表視為方向性的指引，而非測量的替代品。
| 背景類型 | 通常站得住腳的陰影方向 | 為什麼同一組數字可能會出問題 |
|---|---|---|
| 平面淺色表面（接近白色） | 小的向下偏移、低模糊、較深的陰影顏度 | 大偏移會產生複影；高模糊會降低小字的清晰度 |
| 平面深色表面（接近黑色） | 低透明度的柔和淺色陰影搭配小幅偏移 | 生硬的黑底深色陰影會消失；大模糊會將字形洗進背景中 |
| 飽和或品牌色表面 | 中性化的陰影顏度、適度的模糊、仔細的對比檢查 | 陰影會染上背景的色相，可能無法與文字區分開來 |
| 帶圖案或照片的表面 | 較低的模糊搭配與背景中位色調更強的顏度對比 | 模糊會擴散進圖案中，並與字形競爭 |
質性的重點是：在某個背景上看到的任何視覺改善，在另一個背景上可能就是退步。請務必針對實際的背景去測量前景文字的可讀性，而非針對陰影本身，同時也絕對不要把裝飾性的陰影當作文字對比的替代品。
將一個通過稽核的圖層整合進你的權杖系統
一旦宣告看起來正確，請用既有的顏度權杖取代字面值，避免在元件庫中到處散布十六進制色碼。單一行陰影可以整齊地放進一個字型或高度的權杖中，而精簡的輸入合約意味著每個欄位都恰好只做一個決定：由哪個權杖提供偏移、由哪個權杖提供模糊、由哪個權杖提供顏度。這個對應關係比起多圖層堆疊 —— 其圖層順序在重構開始時就會變得舉足輕重 —— 要容易檢視得多。
這也避免了陰影堆疊常帶來的警訊。堆疊多個圖層會讓文字變得混濁、增加繪製負擔，並遮蔽原本的字形。如果目標真的是描邊效果，多層陰影有時可以勉強達成，但使用描邊、SVG 或其他設計手法或許能傳達得更清楚。單圖層產生器是一個刻意的限制，而非遺漏的功能。
What the generator cannot certify
Validated bounds are not the same as a production guarantee. The tool cannot certify accessibility, performance, or compatibility for a particular product, and it intentionally omits font family, weight, size, line height, transitions, and animation because those properties belong to the host typography system. The shadow that looks crisp at 16 px on a laptop may shimmer on a phone, and the shadow that holds contrast at zoom 100 percent may collapse at zoom 200 percent or in forced-color mode.
Strong offsets create double vision, and large blur can reduce clarity for small type. Text shadows also affect rendering cost when applied to large text, many repeated nodes, or animated values, so keep layers limited and avoid continuously animating blur. Check zoom, high-contrast and forced-color modes, dark themes, screenshots, printing, and every background the text can cross.
Avoid using shadow direction or color as the only cue for state. Headings, buttons, and links still require semantic structure and visible focus treatment. The grammar is fully documented in the W3C CSS Text Decoration specification and the MDN text-shadow reference; turning one audited line into accessible, performant markup belongs to the component that hosts it.
For a deeper look, see How to Get a Directory Tree in CMD as Shareable Text.