Usage

這個 Design System 由兩樣東西組成：一份 token 檔（style.css）與一個 React 組件庫（@olab/components）。兩者都住在 production repo（OpinionLabs/frontend）的 packages/ 底下，本站是它們的鏡像與說明。

在 production 使用

全站 CSS 入口先載入 Tailwind，再載入 style.css。所有顏色、字級、間距、圓角的 utility class 都從這份檔案長出來。

@import "tailwindcss";
@import "../packages/configs/style/style.css";

一般頁面從套件根目錄引入；React Server Component 裡改用 /server 入口（production 的 Footer 就是這樣用 Icon、Inline、Stack）。

import { Button, Tabs, Modal } from "@olab/components";
import { Icon, Inline, Stack } from "@olab/components/server";

token 分兩層。組件與頁面只用第二層；第一層只在 style.css 與 Foundations 頁面上看得到。

Tier 1 · Primitive

色階本身，名字不帶語意：neutral、brand、jungle、cherry、gold、sea、ash 等，每條 50–950。

--color-jungle-500

Tier 2 · Role

用途名，指向某一階，並且分 dark / light 兩個值：text-primary、bg-secondary、outcome-yes-solid、team-home-solid、data-fill 等。

bg-outcome-yes-solid

不寫 hex、不寫 bg-[#xxx]、不用 Tailwind 預設色（text-red-500）。
不在組件裡直接用 Tier 1（bg-jungle-500）；一律用 Tier 2（bg-outcome-yes-solid）。
需要的 role 不存在時，先在 style.css 補齊（含 hover / pressed / disabled、dark 與 light 兩個值），再拿來用。

dark 是預設值，寫在 style.css 的 @theme 裡；light 的值寫在 :root[data-opinion-theme="light"] 底下，只覆蓋需要變的 role。

切換方式是在 <html> 上設 data-opinion-theme。production 在頁面最前面用一段小腳本讀 localStorage 的 opinion-theme（預設跟隨系統），把結果寫到這個屬性上。

設計以 dark 為準；light 由 token 自動換值，不逐頁另外設計。

<html data-opinion-theme="light">  <!-- 不設 = dark -->

本 repo 的 Next.js 站另有一層 live-bridge.css，讓 production token 與站點本身的樣式並存。組件要拿到正確的顏色，有兩件事要做：

@olab 組件與用 token 手刻的產品組件，外層要有 className="live-scope"。/live 底下的頁面已由 layout 統一包好；其他路由自己包，範圍取最小即可。

<div className="live-scope">
    <Button skin="brand">Buy</Button>
</div>

站上的 dark / light 切換鈕會同步設定 data-opinion-theme，頁面不需要自己處理。雙擊即開的單檔 HTML 原型沒有站殼，要在 <html> 上自己設：light 加 data-opinion-theme="light"，dark 不設。

<html data-opinion-theme="light">
  <body><div class="live-scope">…</div></body>
</html>

本 repo 需要、但 production 還沒有的 token，放在 live-bridge.css 開頭的本地層，不改 style.css 本體——style.css 必須保持是 production 的原樣，下次同步才不會互相覆蓋。

packages/components 與 packages/configs 由腳本從 production 同步。腳本預設只預覽差異，加 --apply 才寫入；寫入後要重建組件的 dist，/live 頁面才會看到新版本。每次同步的紀錄在 Changelog。

npm run sync-mirror           # 預覽差異
npm run sync-mirror -- --apply   # 寫入