Design System 文件化（下）— 設計師如何將 components 變成開發團隊看得懂的文件？
本文是以設計師的角度，分享 design system 文件化的步驟，並將重點放在可依據的準則建立文件規範，讓開發團隊人員逐步實踐文件化。
回顧上一篇，介紹了如何建立 components，接下來終於要介紹如何將 components 文件化。
若說有沒有必要將 components 文件化，其實是不一定，在開發資源不足的情況下，看設計稿也許就已經足夠溝通了，那為什麼我們還是選擇文件化？
1. 為什麼選擇文件化？
我們使用 zeroheight 文件化 design system，一開始是看到其他公司都有，我們也想要的概念，但某件事發生後，文件化從 nice to have 變成 must have 了。
1–1. 關鍵事件
設計 form 表單時，由於需要處理各種的驗證行為與體驗，到底是使用 on blur 驗證還是 debounce 驗證， 兩個的差異是什麼，經過幾次的討論後，就發現 PM 已經不記得了，換了別的專案處理 form 時，只覺得似曾相似，但驗證邏輯開始換設計師不記得了，這種輪迴終於讓設計師燃起一定要把 design system 文件化的決心。
1–2. 優點介紹
文件化的優點如下：
- 能夠清楚的條列規範細節與邏輯，幫助搜尋查找
- 能夠讓開發人員對於 components 在呈現或動效等有共同的理解，減少錯誤認知
- 能夠減少溝通成本，降低在 spec 與設計稿贅述 components 細節的狀況
2. 將 Figma components 文件化
對於我們來說，建立好 Figma components 只是完成 1/2 ，剩下 1/2 是將 components 文件化，而文件化的步驟如下：
- 參閱各大間的 Design System
- 跟工程師討論可能性與限制
- 依照書寫規則編寫初稿
- 與設計師和工程師驗收內容
- 發布並通知開發團隊進度
2–1. 參閱各大間的 Design System
由於我們的是使用建立好的 Figma components 後隔了一段時間，才在專案空檔開始進行文件化的步驟，所以在文件化之前，還是會先翻閱知名的 design system，看看他們是如何將 components 文件化，幫助我們獲得靈感和指引，了解與彼此的差異，以及可加強之處。
在搜集資料階段有一個非常好用的網站，the component gallery 把非常多知名公司的 Design System 依照 components 類型彙整進來，給我相當大的幫助。
還沒有發現這個網站之前，我需要打開多間公司的 design system，查閱有想看的 component 介紹，有時候還不見得找得到，而 the component gallery 能用關鍵字搜尋特定 components 的文件，搜尋結果頁還會提醒結構功能相同但命名不同的狀況，很貼心！
The component gallery 大概收錄了 90+ 間 design system，並加上程式語言、無障礙與開源等分類，相當實用！如果有你喜歡但是沒有出現在這裡的 Design System，可以寄信請他們加上。
同場加映另外一個彙整 design system 的網站 Adele，不過我比較喜歡 the component gallery。
2–2. 跟工程師討論可能性與限制
在文件化之前，我們還需要跟工程師討論一下我們的 components 是否能夠被正確地實現，確保技術上的細節可行，並且符合設計師與工程師雙方的期望和要求。
我們可以跟工程師討論以下幾個方面：
- components 的結構和屬性，例如是否有變數、是否有狀態等
- components 的交互和邏輯，例如是否有事件、是否有條件、是否有動畫等
- components 的兼容性，例如是否支援不同的瀏覽器、是否支援各種裝置、是否支援多語言等
通過跟工程師討論，我們可以發現和解決一些潛在的問題，產品現階段的限制，以及未來的可擴充性，並且讓雙方對 components 達成一致的目標與共識。
以 tooltip 為例，我在編寫文件前，參閱了 Bootstrap、Google Material Design、Carbon、sprout social 和 Atlassian 的文件說明，才了解無障礙、過度動畫與方向等呈現都有優化空間，例如 Bootstrap 的 Design System 提及透過鍵盤操作的無障礙使用者沒辦法透過滑鼠 hover 行為觸發 tooltip 的出現，所以建議將 tooltip 加在 HTML elements 中，才可以讓無障礙使用者透過鍵盤也能夠在瀏覽頁面時，找得到關注焦點與良好互動。
Making tooltips work for keyboard and assistive technology users
You should only add tooltips to HTML elements that are traditionally keyboard-focusable and interactive (such as links or form controls). Although arbitrary HTML elements (such as
<span>s) can be made focusable by adding thetabindex="0"attribute, this will add potentially annoying and confusing tab stops on non-interactive elements for keyboard users, and most assistive technologies currently do not announce the tooltip in this situation. Additionally, do not rely solely onhoveras the trigger for your tooltip, as this will make your tooltips impossible to trigger for keyboard users.
閱讀了五間公司 tooltip 文件後，我整理出一些想要優化的方向，跟工程師討論是否能實作：
Q. Tooltip 是否可以有預設出現方向，但能依照瀏覽空間調整出現方向？
A. 目前不可行，計算可能會變複雜很耗效能 。
Q. Tooltip 是否達成用滑鼠 hover 和鍵盤 focus 出現？
A. 這是非必要功能 ，可以做得到，但要確認目的及維護複雜度。
Q. Tooltip 是否可以補上過度動畫？
A. 可以加上 fade-in 與 fade-out 效果。
Q. Tooltip 是否可補上寬度設定？
A. 可以有最大寬度設定。
Q. Tooltip 的內容為英文時，首字母是否可以大寫？用 CSS text-transform:capitalize 達成訴求。
A. 可以這樣處理。
2–3. 依照書寫規則編寫初稿
確保我們的 components 是可行的之後，我們就可以開始文件化了。
我們使用線上軟體 zeroheight 編輯文件，貼入 Figma 連結把設計檔內 components 和 layers 上傳同步到 zeroheight，不動用開發資源就能建立有目錄、分頁、搜尋的 design system，附上以前寫的舊文，可以了解透過 zeroheight 能完成哪些規範。
由於撰文者可能不會只有一位，書寫風格與結構最好不要有過多差異，且文件化的目的是讓開發團隊能夠清楚地理解和使用我們的 components，所以我們要盡量寫得清晰、完整、準確和一致。為了達到這個目的，我們需要定義和遵守書寫規則，書寫規則可以包括以下幾個方面：
- 格式和結構，例如使用哪種文件工具（zeroheight、notion等）、使用哪種文件結構（分類或階層）等
- 內容和範圍，例如包含哪些元素（名稱、屬性等）、包含多少細節、包含多少範例等
- 風格，例如使用哪種語氣（正式或非正式）、使用哪種人稱等
- 措辭，例如使用哪種語言、使用英文的大寫或小寫、使用單複數、使用全名或縮寫
我們參考知名公司的文件，並在多次編寫的過程中，整理出 8 個書寫規則與細項，包含以下幾個部分：
- 簡介（Info / When not to use）
- 外觀（Type / Style / Size）
- 架構（Placement / Position / Structure）
- 交互行為（State / Behavior）
- 應用（Dos & Don’ts / Usage）
- 無障礙規範（Accessibility）
- 規格（Border radius / Click area / Dimension / Placement / Position / Spacing）
- 斷點（Breakpoint）
2–3–1. 簡介
- Info
- When not to use Info
Info 會簡述 components 的用途，例如 Tooltip 是漂浮呈現的額外資訊，透過滑鼠 hover 或 click 特定 UI 元素出現。
When not to use 會提及甚麼情況下不適合使用該 components，比如說，當我們在介紹 tooltip 時，我們會在 When not to use 告知 tooltip 裡面不可放置連結，如有需要可以使用結構與 tooltip 相似但可以放連結的 popover。
2–3–2. 外觀
- Type
- Style
- Size
Type 歸類為 components 內功能相同但結構有差異的狀況，我們的 New Feature Badge 有分成有文字的版本和小圓點版本。
Style 則是結構相同，但樣式有差異的狀況，比如說依照一般通知、警示訊息或者錯誤通知而有不同類型的 announcement。
Size 則是根據某些變化而有尺寸差異，例如我們的 button。
2–3–3. 架構
- Placement
- Position
- Structure
Placement 表達的是 components 在瀏覽器上如何呈現，例如我們用藍色色塊示意 announcenment 在桌機版與手機版的位置。
Position 介紹的是 components 間絕對位置，假如有一個 button 可以觸發 tooltip 出現，我們可以安排 tooltip 出現在 button 的上下左右其中一側。
Structure 將每個 components 拆解並個別介紹，如果是非必要( optional )元素，也會標注提醒。
2–3–4. 交互行為
- State
- Behavior
State 介紹 components 在各種狀態的變化。
Behavior 會說明 components 本身的行為與邏輯，有時候會搭配動畫呈現來幫助理解，編寫 tabs 的 scrollable 和 sticky 行為時，比起用文字描述，有滑動行為的動畫更好理解。
2–3–5. 應用
- Dos & Don’ts
- Usage
Dos & Don’ts 會附上圖片解釋 components 的正確用法和錯誤用法。
Usage 會用圖片展示 components 在產品實際使用狀況。例如在寫 pagination 文件時，加入線上實際應用的截圖示意。
2–3–6. 無障礙規範
Accessibility 會介紹使用什麼樣的技術或方法能更體貼少數使用者，讓他們有好的操作體驗。比如說我們請工程師開發 pagination 時，可以請他們在實作 components 時：
- pagination 本身使用 <nav> tag 包住，並加上 attribute
aria-label="pagination"表示其目的 - 在 disabled 的上下一頁 button，加上 attribute
tabindex="-1"，讓鍵盤操作可略過該 disabled 物件
考量到 Accessibility 是設計師和工程師都不太熟的領域，以及開發資源的配置，目前被視為 nice to have 的規範，希望未來能納入 must have 的領域。
2–3–7. 規格
這個段落會標註 components 的組成參數、長寬限制或者位置等，方便工程師開發時參考，避免造成開發上的錯誤。
- Border radius
- Click area
- Dimension
- Placement
- Position
- Spacing
Border radius 出現在 components 裡時，在有圓角的地方標註。
Click area 會用遮罩標註可點擊範圍，沒有底色和邊線的 button 很需要有遮罩示意。
Dimension 標注 components 最基本的寬高以外，還可能會標註 components 的最大或最小寬高，彈性尺寸或者比例。
Placement 標註 components 在瀏覽器的位置，下圖是 flash notice 在手機版需要靠近左下方，並保持特定的間距。
Position 標註 components 間絕對位置的參數，下圖的 badge 超出右上方 8px，但沒超出可點擊範圍。
Spacing 標註 components 的間距。
2–3–8. Breakpoint
僅針對因為裝置切換或者寬高變動，產生外觀變化的情況作標註，例如輸入欄位在桌機和手機使用的樣式不一樣。
儘管這 8 個書寫規則裡的細項看起來很多，實際上不是每一個規則細項都需要寫入文件裡，例如編寫 breadcrumb 時，我們其實只有寫到：
- 簡介 ( Info)
- 架構 ( Structure )
- 交互行為 ( State )
- 應用 ( Dos & Don’ts / Usage )
- 規格 ( Dimension / Spacing )
書寫規則只要當作一個檢查清單就好，重點是使用這個框架釐清思路，並完成一份清晰易讀、格式統一和內容正確的文件，讓開發團隊所有成員有共同的理解。
2–4. 與設計師和工程師驗收內容
在完成文件的初稿之後，我們會在設計團隊傳閱，確認一下我們的文件是否準確、完整和易讀，即時修改遺漏的細節或微調錯誤，確認無誤後，再交給工程師確認行為與邏輯的部份，是否與當初的討論匹配。發布文件之前，我們要確保我們的文件是可靠的，並且同時符合雙方的期望和需求。
我們可以與設計師和工程師確認以下幾個方面：
- 文件的完整性，例如是否包含了所有的屬性、是否描述了所有的用途和規則、是否展示了所有的範例等
- 文件的準確性，例如是否有拼寫或語法錯誤、是否有數據或邏輯錯誤、是否有不一致或矛盾的地方等
- 文件的可讀性，例如是否有足夠的空白和分段、是否有合理的標題和列表、是否有適當的示意圖等
通過與設計師和工程師確認，我們可以及時發現和修改一些問題，並且讓雙方對於文件的產生有更多的信任和參與。
2–5. 發布並通知開發團隊進度
確保內容無誤之後，我們就可以發布文件了，在發布之後，我們還需要通知開發團隊我們的進度，讓他們知道我們已經完成了哪些 components 的文件化，以及他們可以從哪裡查看和使用，增加開發團隊對我們的文件的關注和使用，提高團隊成員對產品的理解程度，降低錯誤認知以及減少溝通成本。
3. 結語
收集、討論、撰寫、驗收與發布，是我們如何將 components 文件化的步驟，雖然這文章看起來很長，過程看起來也很耗時，但實際執行時間可能比想像中短，如果是樣式和邏輯單純的 components，例如 breadcrumb 或 pagination，整個流程有可能三個工作天就完成了（還是你們覺得三天也太長！？）。
這是我們公司將 components 文件化的過程，謝謝設計師們，開發團隊還有 Bing AI，如果有一些問題和想法歡迎各位討論與分享。
最後，AsiaYo 目前在招募 Sr. Product Manager、Mid. Frontend Engineer、Mid. Backend Engineer，詳細資訊請參考 104，歡迎成為我們的夥伴！
