撰寫樣式

全域樣式

載入一個應用程式進入點、依職責拆分共用 CSS，並將文件預設值、元件規則與路由樣式放在適當範圍。

本頁目錄

讓應用程式集中從一個位置載入每個頁面需要的樣式。這個進入點可以匯入多個原始檔：將共用值、文件預設樣式與元件規則保留在各自所屬來源，再透過同一份應用程式樣式表組合。

請先完成框架安裝。下方範例擴充既有 CSS 進入點，不需要再次安裝 Master CSS。

#從一個應用程式進入點開始

在應用程式已載入的樣式表開頭，保留預設匯入：

styles/app.css

@import '@master/css';

此匯入會帶入預設集定義與基礎樣式，包含 theme, base, defaults, components, utilities 的順序。整合以這個進入點傳遞專案產生的 CSS。請依框架安裝指南，從應用程式根元件、根版面配置或建置進入點匯入。

拆分原始檔不需要另一個完整進入點。從 app.css 匯入你自己的檔案：

styles/app.css

@import '@master/css';@import './theme.css';@import './defaults.css';@import './components.css';

這些檔案組成同一個進入點圖。無論直接寫在 app.css 或某個匯入檔，共用定義都可使用。避免在每個路由樣式表重複匯入完整 Master CSS 進入點：那會讓每個檔案都成為進入點，並可能重複全域原生 CSS。

#設定文件預設樣式

將預設集重設樣式保留在 base。產品的文件預設樣式則放進 defaults，讓一般元件與 utility 宣告能覆寫它們：

styles/defaults.css

@layer defaults {  body {    background-color: var(--color-surface-base);    color: var(--color-text-body);  }}

不加額外類別就應取得預設樣式的元素，請使用原生選擇器。有意識地控制選取範圍：全域 button 規則也會作用於每個功能內的按鈕。若規則屬於某個產品角色，請使用元件類別。

預設集基礎樣式已將字型 token 套用到文件。選擇字型時，依文字排版調整這些 token。宣告互相競爭時，請參閱串接層；較晚載入規則，不會使它進入更高優先的串接層。

#決定哪些內容屬於共用圖

共用決策	定義位置	延伸閱讀
使用端應一起改變的值	`theme.css` 中的 `@theme`	主題 token
每頁都需要的預設樣式	`@layer defaults` 中的原生選擇器	上方範例
反覆出現的產品元素	`@layer components` 中的原生類別	重用樣式
使用時才產生的類別能力	匯入樣式表中的 `@utility`	下方輔助類別範例
重複的 CSS 宣告或巢狀樣式	`@mixin`，以 `@apply` 展開	CSS 重用
具名檢視區或容器條件	`@custom-media` 或 `@custom-container`	響應式設計

匯入的 theme.css，可從專案需要的值開始：

styles/theme.css

@theme {  --spacing-card: 1.5rem;}

此 token 會註冊 p-card、gap-card 與其他接受該鍵名的間距家族。專案需要時才會輸出宣告；放進進入點圖，不會使一般 token 變成靜態。

因為語意共用，才共用定義。兩個功能今天使用相同數字，仍可能需要不同 token；一個元素用了多個類別，本身也不代表需要元件抽象。

#明確保留元件歸屬

例如，共用通知元件可放在 components.css：

styles/components.css

@layer components {  .notice {    padding: var(--spacing-md);    border: 1px solid var(--color-line-divider);    border-radius: var(--radius-md);    background-color: var(--color-surface-raised);    color: var(--color-text-body);  }}

<aside class="notice">Your changes are saved locally.</aside>

此原生選擇器為 .notice 套用樣式，不會註冊名為 notice 的 utility。將共用狀態與條件寫在元件規則內。若需要接受 Master CSS 修飾詞的類別組合樣式，請改用 @utility。重用樣式以可操作範例比較這些選擇。

進入點圖中的原生 CSS 預設會輸出，包括未使用的元件規則。原生修剪需要明確啟用；請參閱原生修剪。不要只為讓定義可見，就把大型路由專用樣式表移進全域圖。

#加入共用輔助類別

全域定義能描述多個功能需要的行為，而不必為每種可能類別都產生規則。這些輔助類別排列相關連結、允許畫面外內容略過渲染工作，並在列印時隱藏整組內容：

共用輔助類別，一組相關連結

@utility flow {  display: grid;  gap: var(--spacing-md);}@utility content-auto {  content-visibility: auto;  contain-intrinsic-size: auto 32rem;}@utility print-hidden {  @media print {    display: none;  }}

<section class="content-auto flow print-hidden p-md b-solid b(1) b-line-divider r-md bg-surface-raised">  <h2 class="m(0) text-lg font-regular">Related guides</h2>  <a class="text-sm fg-text-body underline" href="/guide/theme" target="_top">Choose shared theme values</a>  <a class="text-sm fg-text-body underline" href="/guide/responsive-design" target="_top">Adapt a layout to its available space</a></section>

產生的 CSS

@layer theme {  :root,  :host {    --color-zinc-30: oklch(78% .0025 265);    --color-zinc-70: oklch(39.8% .0028 265);    --color-zinc-90: oklch(24.6% .0022 265)  }  :root,  :host {    --color-surface-raised: light-dark(var(--color-white), var(--color-zinc-90));    --color-line-divider: light-dark(oklch(0% 0 none / .12), oklch(100% 0 none / .12));    --color-text-body: light-dark(var(--color-zinc-70), var(--color-zinc-30))  }  :root,  :host {    --color-white: oklch(100% 0 none)  }  :root,  :host {    --font-weight-regular: 400;    --font-size-sm: .875rem;    --font-size-lg: 1.125rem;    --text-sm: var(--font-size-sm);    --text-sm--line-height: 1.5;    --text-sm--letter-spacing: 0;    --text-lg: var(--font-size-lg);    --text-lg--line-height: 1.5;    --text-lg--letter-spacing: 0;    --radius-md: .375rem;    --spacing-md: 1rem  }}@layer utilities {  .text-lg {    font-size: var(--text-lg);    line-height: var(--text-lg--line-height, normal);    letter-spacing: var(--text-lg--letter-spacing, normal)  }  .text-sm {    font-size: var(--text-sm);    line-height: var(--text-sm--line-height, normal);    letter-spacing: var(--text-sm--letter-spacing, normal)  }  .content-auto {    content-visibility: auto;    contain-intrinsic-size: auto 32rem  }  .flow {    display: grid;    gap: var(--spacing-md)  }  @media print {    .print-hidden {      display: none    }  }  .bg-surface-raised {    background-color: var(--color-surface-raised)  }  .b-line-divider {    border-color: var(--color-line-divider)  }  .r-md {    border-radius: var(--radius-md)  }  .b-solid {    border-style: solid  }  .b\(1\) {    border-width: calc(1 * 1px)  }  .fg-text-body {    color: var(--color-text-body)  }  .font-regular {    font-weight: var(--font-weight-regular)  }  .m\(0\) {    margin: calc(0 * 1px)  }  .p-md {    padding: var(--spacing-md)  }  .underline {    text-decoration-line: underline  }}

flow 提供網格與間隔。print-hidden 在列印媒體隱藏整組內容。content-auto 可略過畫面外渲染；32rem 固有尺寸是備援估計值，並非固定區塊高度。

將定義放在既有 Master CSS 匯入之後，或從應用程式進入點匯入 utilities.css。類別在標記中被發現時才產生 CSS。請在應用程式開啟列印預覽，檢查 print-hidden；若連結也應出現在列印中，移除該類別。依自己的版面配置內容，選擇固有尺寸估計值。

跨頁檢查與依輸出逐步最佳化的流程，請參閱最佳化 CSS 傳遞。

#區域樣式維持區域傳遞

讓應用程式進入點專注於跨頁共用樣式。整合會為路由樣式表提供專案定義，無須再次完整匯入 Master CSS。圖之外的其他定義請使用 @reference；它不會傳遞被參照的原生 CSS。路由載入器仍負責傳遞區域規則。

此設定請參閱路由層級樣式；獨立應用程式需要各自的進入點圖時，請參閱 Monorepo。拆分全域檔案後，檢查一個使用其定義的頁面與一個未使用的頁面：共用樣式仍應由應用程式進入點傳入，路由專用規則則應保留原本的區域歸屬。