設計系統「規範文檔」編寫指南 · 第二篇 - 組件簡介

來自專欄 Scope Lane

本篇譯自 Nathan Curtis 的文章：Component Instructions

組件：「大家好，我的名字是…」

為物體起名字是非常必要的，但有時這麼一件看似簡單的事情卻會變得很困難。

組件的名字會出現在文檔頁面的標題中，網站的導航或麵包屑上，還有代碼里。例如按鈕（Button）是我們很容易在命名上達成共識的一個簡單組件。

而為像 Drawer 或 Accordion 或 Collapsible 這種可以摺疊並收起的組件命名則是個棘手的事情。有沒有比這更難的呢？例如為像 Grid（網格） 或 Layout（布局）這種用來為頁面製造視覺秩序的底層結構組件命名時，我們就可以看到各種各樣的名稱，如：Layout Grid（布局網格）或 Rows & Columns（行與欄）或 Box（盒子模型）或 Proportional Grid（比例網格）。甚至 Card（卡片） 都不是被廣泛一致地定義的：Card 是僅僅指這個容器還是也包含了裡邊的內容？

對於大多數設計系統網站來說，導航都是用純文本的形式呈現的。其實我們可以稍加一些修飾來讓導航更直觀，比如在組件列表視圖中加上對應的縮略圖，或是在 Hover 時出現預覽圖。

你還可以在組件簡介中為組件加上一個「也被稱作：XXX」的描述：

Takeaway：為組件想出一個一眼就能看明白的名稱是很難的，所以我們要適可而止，不要花費太多時間在命名上。而是應該用更巧妙的方式來解決這個問題。

Button 還是 Buttons？複數和單數的形式怎麼選？

代碼裡邊的規則是單數形式（-button，-input，-card）。對於那種可能會在一個頁面里使用到多次的組件，不論是結構簡單的（如 Buttons，Inputs）還是複合型的（如 Dialogs，Modals），行業內普遍的做法是在頁面標題以及站點導航中使用複數形式。

不過，單數形式倒是常用於那種只會在單個頁面出現一次的組件上。比如 Global Navigation（全局導航），Footer（頁腳），Grid（網格） 這些組件是一個頁面的基礎框架；相似地，Masthead，Hero 或 Billboard 是一個頁面的氣質的基礎，不會在同一個頁面出現多次，因此我們使用單數形式來描述它們會更合理。

Takeaway：大多數團隊採用了複數形式，但每個團隊都有自己的決定權。如果你想要混用單數與複數形式，請確保你有足夠可靠的邏輯來支撐。

組件介紹：「我是用來…的」

只有名稱是不足以完成一個組件的介紹環節的。因此我們還需要一段簡介來描述組件的本質。

用 Deck 來引導讀者

簡介可以是很簡短的：

Buttons can be used to show the user』s choice of options for actions and assign these to a clear hierarchy. (Audi)

Grid systems are used for creating page layouts through a series of rows and columns that house your content. (IBM Carbon)

簡介是版面設計中的一種傳統模式，被稱作 Deck，通常出現在標題與正文之間，並且與正文在視覺上有明顯區分，字型大小會介於標題與正文之間，比正文字型大小大一些，使得讀者不會遺漏這部分。

保證 Deck 的長度和一條 Tweet 差不多

多長才是過於長？我推薦大家參照 144 字左右的 Tweet（國內即微博） 長度。並且盡量只用一個句子完成簡介。

在寫簡介時，一定要捕捉本質，而不要過於追求全面。也就是說要理清楚組件的結構和目的，而不是使用時的各種細節。例如就沒有必要在「網格」的簡介中出現 「 768px 或 1280px 的 breakpoints」 等過於詳細的字眼，而是換成簡單的「欄和行」， 「響應式」等等字眼。

Takeaway：要把握組件的本質，避免太執著於具體功能，並且保持足夠簡短。

一些能夠激發靈感的業內案例

對於按鈕：

The Predix UI Buttons module is a simple, robust, extensible baseline for building entire suites of buttons on. (GE Predix)

Predix UI 里的按鈕模組是一種簡潔、穩固、可擴展的基礎組件，可以用來創造一系列的按鈕套裝。

Buttons make common actions immediately visible and easy to perform with one click or tap. They can be used for any type of action, including navigation.(Shopify)

按鈕使得常見的操作能夠被輕鬆發現，用戶可以使用點擊或按壓行為來激活。它們可以被用來承載各類操作，也可以用作導航。

Buttons are used for actions, like in forms, while textual hyperlinks are used for destinations, or moving from one page to another. (Github Primer)

按鈕被用來承載操作，例如在表單中，文字鏈接被用來承載目的地或前往其他頁面的操作。

Buttons are used to invoke an event. (Salesforce Lightning)

按鈕被用來觸發事件。

對於卡片：

Provide entry into detailed content via an image, text, and related information. (Discovery Comet)

通過圖片，文字和相關的信息來為更詳細的內容提供入口。

A card is a sheet of material that serves as an entry point to more detailed information. (Material UI)

卡片就是作為詳細信息入口的一種材料。

Cards contain elements and functions on a single topic and can be used as teasers for further content. (Audi)

卡片包含了特定主題下的元素和功能，並且可以作為其他內容的入口。

對於網格（布局）：

This 12-column, responsive grid provides structure for website content. (USDS)

這個 12 欄的響應式網格為網站內容提供了整體結構。

The grid provides the foundation for harmoniously positioning elements, while maintaining a consistent and coherent look to the screen. (Atlassian)

網格提供了和諧整齊地排列頁面元素的基礎，同時保證了屏幕中界面的統一性與整體性。

Box component provides an easy way to apply standardized size & space to your layout. (Mineral)

Box 組件為在版式中應用標準的尺寸與間距提供了一種簡潔易懂的方法。

避免過於詳細的簡介

有些組件由於本身比較難以定義或大家的共識比較模糊，需要簡介里針對定義、概念作出詳細的描述。

比如版式網格的文檔。Rows（行），columns（欄），breakpoints（斷點），alignment（對齊），shifting（位移微調），stacking（堆疊），offsetting（縮進）。天啊，需要關注的點太多了。只是想一想就已經很累了。

所以我們的直觀感覺就是要描述的細緻入微。一段簡介變成了一個區域。代碼展示案例被擠到了頁面的底部。讀者在剛開始閱讀的時候就接收了太多細枝末節的信息。

讀者辨識組件時更多靠的是直觀的案例（圖片），而不是名稱（文字），即便他們在溝通或回想時會先想到組件叫什麼名稱。因此，要把組件名稱（文字）和代碼案例（圖片）放在一起。我們為組件文檔做的可用性測試證實了：

「我不想讀這麼多字」

「給我看我能直接用的東西（部分）」

「直接跳到核心部分」

「有沒有什麼實用的工具可以給我直接用？」

對於組件簡介來說，避免過於深入的場景設定和冗長的總結性文字。把功能細節，設計與代碼的內容留給接下來的模塊來描述。

組件簡介一定要言簡意賅。這個模塊的目標是讓讀者知道他來對了地方。組件名稱和實際組件案例之間的距離不要太長，這樣對讀者來說才是友好的。

設計系統專欄往期內容：

VOL.01: UXPin Design System Virtual Summit 系列·第一篇