[Stitches] Style your components with confidence

Stitches is a lightweight, performant styling library with a focus on component architecture and developer experience.

Published in

Starbugs Weekly 星巴哥技術專欄

10 min readFeb 20, 2022

開發網站時，不管有沒有使用 UI framework 上（Ant Design、element UI…) ，多少都會有專屬的 styling/theme guide。如何維持網站整體風格一致、寫出簡單清楚並好維護的 css 也是重要課題之一。今天並不會探討如何做出一個完整的 Design system 因為那實在是太博大精深，要介紹的只是一個 css in js 的 library Stitches (這兩年才剛推出的超新工具)，幫助你在寫 styling 的時候更容易維護。

Stitches 的 document 寫得相當清楚好讀，這一篇也是以官方文件為基底，自己實戰經驗為輔寫出來的。

Stitches 完全支援 TypeScript (但你也可以選擇不用)
除了 @stitches/react 只支援 React，若使用其他 Framework 也可以是用 @stitches/core 且用法大同小異，不過我自己是寫 React 所以此文會以 @stitches/react 的寫法做範例

🔖 文章索引1. 一窺 Stitches
2. Configure Stitches: 定義規範
3. styled: 套用在 component
4. css: 覆蓋樣式
5. 小結 + 為什麼會有這篇文章之碎念

一窺 Stitches

入門 stitches 零學習成本，因為就是我們熟悉的 CSS 語法 (跟 style component 也頗像)，不過要到進階用法還是額外多花幾個小時學習

Configure Stitches

Create your config file

stitches.config.ts是我覺得客製 Styling 最重要的一支檔案，也是網站風格的基礎。裡面需要定義的東西很多，除了基本的 theme color、字型大小粗細行高等等，還有 spacing 間距、Responsive width 等等都會放在裡面，網站裡所有的 components 都要照著這個 config 設定規範才能有一致的風格

看更多 Defining token

createStitches 可以分為五大部分

theme

定義你的 styling rule，只要更改這隻檔案，所有網站 styling 都會同步更新

這邊就是定義顏色字型大小等等，先以最簡單的顏色做示範

第一種抓值法: '$blue’

我在 config 裏定義藍色 blue: ‘mediumblue’ (mediumblue 是 css 本來就有的預設顏色，註一)，使用時直接用 background: '$blue’ (記得要加引號跟 $)就可得到這個深藍色。

為什麼 stitches 知道要去抓 colors 裡面的 blue 而不是 fontSizes 裡面的 blue ?

因為 stitches 有 default 定義一個叫 ThemeMap 的東西，在 line 86 可以看到 background 早就被定義要去抓 colors 底下的 property。當然你可以客製化 ThemeMap 這個檔案，下面文章會提到

第二種抓值法: '$color$blue’

另一種方法就是常見抓值方法 background: '$color$blue'

不過我試過 stitches 最多就只接受兩層，如果我定義出以下三層，然後用 background: ‘$colors$a$blue’，是沒有作用的

❌
const { styled } = createStitches({
  theme: {
    colors: {
      a: { 
        blue: 'mediumblue'
      }
    },
  },
});

最後一種抓值法: theme.colors.blue

theme 是一個包含 token data 的物件，所以也可以利用他抓值 [延伸閱讀: amazon 開發的 Style Dictionary]

media

定義全站 responsive breakpoints

media: {
  sm: '(min-width: 640px)',
  md: '(min-width: 768px)',
  lg: '(min-width: 1024px)',
}

sm、md、lg 這些名稱都是可以隨便取的，不過為了協作更方便，文件建議還是取 bp1, bp2, bp3 或是 sm, md, lg 這種一看就懂的屬性

utils

Create custom utils to improve your developer experience.

utils: {
  m: (value) => ({
    margin: value,
  }),
  mt: (value) => ({
    marginTop: value,
  }),
  mr: (value) => ({
    marginRight: value,
  }),
  mb: (value) => ({
    marginBottom: value,
  }),
  // 略...
})

這個很實用，解救懶人可以少打幾個字專用，這樣以後再也不用打 marginTop 或 paddingbottom ，只要 mt: '2px'、pb: '4px' 搞定

prefix

compile 時幫你加上前綴

createStitches({
  prefix: 'hannah',
});
<button class="c-lgxlSe">Button</button>
變成
<button class="hannah-c-lgxlSe">Button</button>

themeMap

可以自己定義 theme tokens. Learn more.

tokens 在之前文章有稍微提到，目的就是先定義好 token 對應的 Properties

使用時不需要再 width:$space$1 ，只要 width: $1搞定。tokens 名稱是可以隨意取的，像以上範例的 space、hannah ，官方只有建議使用 camel case, pascal case or snake case，我自己是習慣 camel case

styled

定義好最重要的 config 檔後，就可以套用在 component 上了，這篇會提其中兩個最常使用的 styled、css 其他例如 globalCss、createTheme 等等讀者可以自行去官方文件看喔

Base styles

Base styles 零學習成本，用法跟 style component 大同小異

See more Base Styling

Variants

可以一次定義一整組 set，像下圖一樣

範例直接定義 fill、outline、ghost 三種按鈕樣式，只要改變 button 的 color 、size 屬性就可以看到不同 style 的按鈕。另外還可以設定 defaultVariants 也就是預設值按鈕的樣子

若在不同 Device 想呈現不同 style ，就可以運用它提供的 Responsive variants

() => (
   <Button
     size={{
       '@initial': 'standard',
       '@sm': 'small',
     }}
   >
     Button
   </Button>
);

See more variants

CSS: Overriding Styles

How to override styles in the consumption layer.

Stitches 提供 css 這個屬性來覆蓋 styled 定義好的預設樣式，裡面可以有

一般 css backgroundColor: ‘green’ ;
在 config 定義的 tokens backgroundColor: ‘$yellow2’ ;
media queries @sm: {colorL 'yellow1'}’

實際 compile 出來結果並不是用 inline style 覆蓋原有 css，而是他會再生一個動態 class 去取代原本的 class (直接看下圖就很好理解)

See More Overriding Styles

Overriding the HTML tag

另外 Stitches 也提供一個很特別的屬性 as，可以改變 compile 出來的 HTML tag

<Button> Button </Button> → <button> Button </button>
<Button as="a"> Button </Button> → <a> Button </a>

Composing Components

Composing one Stitches component into another.

跟用 css 屬性取代樣式蠻像的。但它的創建一個新 component 樣式取代，不過自己蠻少用的。對我來說還是喜歡先定義好比較清楚也好管理

See More Composing Components

小結 + 為什麼會有這篇文章之碎念

雖然年輕時曾自認為是切版女王 XD，但自從來美國後就再也沒鑽研過 CSS 相關議題了( 四年沒碰了)，早就不知道現在 CSS 發展到哪裡。原因是因為公司分工很細，維護 Design Sysyem 就有一整個團隊，不同產品部門都是複製貼上他們的 Component 然後就開始專注在 JS 邏輯，頂多只是稍微改一下 style component 的樣式而已。

但最近正開發一個全新產品，為了快速生出 POC 所以沒有採用公司原本 Design Sysyem 而是全部客製化，其中就用了 Stitches 這個去年才推出的套件幫助定義新產品 Foundations，用起來還蠻順手所以就想來寫我人生第一篇 CSS 相關主題 Medium 文介紹他。最後此文也沒有列出跟其他套件相比的優缺點，因為自己太久沒碰 CSS 所以也無從比較起…

另外我相信自己早就回到 CSS 菜鳥，所以若文章有錯誤，拜託留言告訴我！

註一:

完全不知道 CSS 就有一堆預設的顏色可以用 (Full List here)，不過大部分時候還是會客製化產品的顏色就是