DESIGN.md 規範

DESIGN.md 格式的正式規範——token schema、章節結構與型別系統。

DESIGN.md 檔案包含兩層。YAML front matter 存放機器可讀的設計 token——代理程式用來強制維持一致性的精確數值。markdown 本文則以 ## 章節組織，提供人類可讀的設計理念。文字說明可以使用描述性的色彩名稱（例如「Midnight Forest Green」），對應到系統化的 token 名稱（例如 primary）。Token 是規範性數值；文字說明則提供套用這些數值的脈絡。

這套規範是一項基礎，而非處方。它提供代理程式、工具與團隊都能倚賴的共同基礎，同時保留為特定領域需求擴充格式的自由。

設計 token

DESIGN.md 將設計 token 以 YAML front matter 的形式嵌入檔案開頭。Front matter 區塊必須以僅含 --- 的一行開始，並以僅含 --- 的一行結束。這些分隔符號之間的 YAML 內容遵循下方定義的 schema。

這套 token 系統的靈感來自 W3C Design Token Format。Token 可以輕鬆地與 tokens.json、Figma variables 及 Tailwind 主題設定互相轉換。

---
version: alpha
name: Daylight Prestige
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
    padding: 12px
---

Schema

version: <string>          # optional, current version: "alpha"
name: <string>
description: <string>      # optional
colors:
  <token-name>: <Color>
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>

<scale-level> 佔位符代表尺寸或間距級距中的具名層級。常見的層級名稱包括 xs、sm、md、lg、xl 與 full。任何具描述性的字串鍵都有效。

Token 型別

型別格式範例
Color# + hex 色碼（sRGB）"#1A1C1E"
Dimension數字 + 單位（px、em、rem）48px, -0.02em
Token Reference{path.to.token}{colors.primary}
Typography複合物件參見下方屬性

Typography 屬性

屬性型別說明
fontFamilystring字型家族名稱
fontSizeDimension字級大小
fontWeightnumber數值字重（例如 400、700）。在 YAML 中，裸數字與加引號的字串等效
lineHeightDimensionnumber
letterSpacingDimension字距調整
fontFeaturestring設定 font-feature-settings
fontVariationstring設定 font-variation-settings

Token 參照

Token 參照以大括號包住，內含一條指向 YAML 樹中另一個值的物件路徑。對大多數 token 群組而言，參照必須指向基本值（例如 {colors.primary-60}），而不是整個群組。在 components 章節內，則允許參照複合值（例如 {typography.label-md}）。

components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"

章節

每份 DESIGN.md 都遵循相同的結構。若章節與專案無關，可以省略；但出現的章節應依照下方列出的順序排列。所有章節都使用 ## 標題。可選擇使用 # 標題作為文件標題，但不會被解析為章節。

章節結構刻意保持開放。標準章節提供共用的詞彙；設計系統可以自由在這些章節之外加入特定領域的章節。

章節順序

#章節別名
1OverviewBrand & Style
2Colors
3Typography
4LayoutLayout & Spacing
5Elevation & DepthElevation
6Shapes
7Components
8Do’s and Don’ts

Overview

另稱「Brand & Style」。對產品樣貌與感受的整體描述。這個章節定義品牌個性、目標受眾，以及 UI 應該喚起的情感反應。當特定規則或 token 未定義時，它會作為基礎脈絡。

## Overview
A calm, professional interface for a healthcare scheduling platform.
Accessibility-first design with high contrast and generous touch targets.

Colors

定義設計系統的色彩調色盤。至少應定義 primary 調色盤。其他調色盤可以自由命名；常見慣例為 primary、secondary、tertiary 與 neutral。

## Colors

The palette is rooted in high-contrast neutrals and a single accent color.

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Secondary (#6C7278):** Sophisticated slate for borders, captions, metadata.
- **Tertiary (#B8422E):** The sole driver for interaction.
- **Neutral (#F7F5F2):** Warm limestone foundation.

設計 token： 一個 map<string, Color>，將 token 名稱對應到它的 hex 色值。

colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"

Typography

定義字體排印層級。大多數設計系統有 9–15 個層級，每個層級都有語意角色（headline、body、label）與尺寸變體（small、medium、large）。

## Typography

- **Headlines:** Public Sans Semi-Bold for an institutional voice.
- **Body:** Public Sans Regular at 16px for long-form readability.
- **Labels:** Space Grotesk for technical data and metadata.

設計 token： 一個 map<string, Typography>，將 token 名稱對應到它的字體排印屬性。

typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
  label-caps:
    fontFamily: Space Grotesk
    fontSize: 12px
    fontWeight: 500
    lineHeight: 1
    letterSpacing: 0.1em

Layout

另稱「Layout & Spacing」。描述版面配置與間距策略——格線模型、間距級距與容器原則。

## Layout

The layout follows a Fluid Grid model for mobile and a Fixed-Max-Width
Grid for desktop (max 1200px). A strict 8px spacing scale is used.

設計 token： 一個 map<string, Dimension | number>，將間距級距的識別碼對應到尺寸值或無單位數字（例如欄數或比率）。

spacing:
  base: 16px
  xs: 4px
  sm: 8px
  md: 16px
  lg: 32px
  xl: 64px
  gutter: 24px
  margin: 32px

Elevation & Depth

另稱「Elevation」。描述視覺階層如何傳達。對於使用陰影的設計，它定義陰影屬性。對於平面設計，它說明替代方法（邊框、色調層次、色彩對比）。

## Elevation & Depth

Depth is achieved through tonal layers rather than heavy shadows.
Background uses a soft off-white; primary content sits on pure white cards.

Shapes

描述視覺元素的形狀——圓角半徑、邊緣處理，以及整體的形狀語言。

## Shapes

All interactive elements use a minimal 4px corner radius.
Modern enough to feel current, rigid enough to feel engineered.

設計 token： 一個 map<string, Dimension>，將級距層級對應到圓角半徑。

rounded:
  sm: 4px
  md: 8px
  lg: 12px
  full: 9999px

Components

元件原子的樣式指引。規範定義了常見的元件類型——Buttons、Chips、Lists、Inputs、Checkboxes、Radio buttons、Tooltips——但鼓勵設計系統定義與其領域相關的額外元件。

## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill, secondary uses outline
- **Inputs**: 1px border, surface-variant background, 12px padding
- **Cards**: No elevation, 1px outline border, 12px corner radius

設計 token： 一個 map<string, map<string, string>>，將元件識別碼對應到一組子 token 屬性。Token 值可以是字面值，也可以是對先前已定義 token 的參照。

變體。 元件可以為不同 UI 狀態（hover、active、pressed）提供變體。變體以具相關鍵名的個別元件項目定義。

components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.primary-70}"

元件屬性 token

屬性型別
backgroundColorColor
textColorColor
typographyTypography
roundedDimension
paddingDimension
sizeDimension
heightDimension
widthDimension

Do’s and Don’ts

實用準則與常見陷阱。這些內容在產生過程中扮演護欄的角色。

## Do's and Don'ts

- Do use the primary color only for the single most important action per screen
- Don't mix rounded and sharp corners in the same view
- Do maintain WCAG AA contrast ratios (4.5:1 for normal text)
- Don't use more than two font weights on a single screen

消費者對未知內容的行為

這套規範的設計用意就是可以被擴充。當消費者遇到本規範未定義的內容時：

情境行為範例
未知的章節標題保留；不報錯## Iconography
未知的色彩 token 名稱若值有效則接受surface-container-high: '#ede7dd'
未知的字體排印 token 名稱視為有效字體排印接受telemetry-data
未知的間距值接受；若不是有效尺寸值則以字串儲存grid-columns: '5'
未知的元件屬性接受並提出警告borderColor
重複的章節標題報錯；拒絕該檔案兩個 ## Colors 標題

建議的 token 名稱

下列名稱在設計系統間廣為使用。它們並非必要，但可作為維持一致性的指引。

Colors: primary, secondary, tertiary, neutral, surface, on-surface, error

Typography: headline-display, headline-lg, headline-md, body-lg, body-md, body-sm, label-lg, label-md, label-sm

Rounded: none, sm, md, lg, xl, full

原文: https://stitch.withgoogle.com/docs/design-md/specification/

本頁翻譯自 Google Stitch 官方文件，原文版權歸 Google LLC 所有。本站為獨立第三方翻譯，與 Google 無關聯。

← 上一頁從程式碼庫匯入下一頁 →檢視、編輯與匯出