bruno-baeta/clean-ui

Clean UI

簡潔、現代的介面，具有淺色與深色主題，符合螢幕尺寸，以資料為優先，且具有由人（而非 AI）打造的產品感。以下規則源自實際的調整要求。每一條規則在被違反時都曾惹惱使用者：請將其視為需求，而非建議。

本技能的檔案

路徑相對於此技能所在的資料夾。

檔案	使用時機
references/informacao.md	每個新畫面或重新設計，在佈局之前。 如何選擇要顯示的內容、優先順序以及每個資訊的位置（庫存、使用者問題、級別、篩選器、位置地圖、書面計畫）。
references/padroes-aprovados.md	使用者已批准的區塊（「變得更好很多了」）：決策卡片、決策度量與閾值線的圖表、含隨時間餘額的情境卡片、使用者自己的列表、季節性支援、手機頁首、按優先順序排序、超寬螢幕。請用作內容的起點，而非固定的骨架。
references/armadilhas.md	已經造成返工的技術錯誤（Tailwind v4、cn 未合併、[&>*]: 的特定性、next-themes、伺服器使用舊 CSS、測試本地資料庫沒有的狀態）。請在撰寫程式碼前閱讀。
references/migracao.md	重新設計整個應用程式（多個畫面）：先建立已批准的參考畫面，再由你建立基礎（框架、頁面零件、body 上的 token、已儲存的主題），具有共同簡報的平行前線，整合（向套件提出請求，僅在最後刪除舊程式碼，重新啟動，驗證所有內容）。
references/exemplos.md	正確與錯誤的真實案例。在建立新畫面或不確定某個東西是否夠好時閱讀。
references/dashboards.md	每個包含數字、圖表或地圖的畫面。 業餘與專業的區別、原則（NN/g, Stephen Few, IBM Carbon）、7 種構圖（選擇符合資訊計畫的一種）、寬螢幕與超寬螢幕的規則、圖表的顏色與修飾。
references/paletas.md	現成且經過驗證的調色盤（Cobalto, Índigo, Ciano, Coral），包含灰色、強調色、有序比例與兩個主題的系列色。請從此處選擇，切勿使用單獨的顏色。
assets/tokens.css	新專案或無品牌識別：淺色與深色主題（遵循系統，可手動切換）、字體、焦點、圖表與觸控已配置（Tailwind v4）。預設附帶 Cobalto 調色盤僅作為起點：請將其替換為所選調色盤的完整區塊（位於 paletas.md 結尾）。包含 tall 變體、正面/負面/警告以及游標指標。
references/exemplos-dashboards/	使用者的 7 個現代儀表板參考。在設計任何儀表板之前，請全部開啟。
references/anatomia-dashboard.md	這些參考轉換為具體尺寸：卡片、標題、指標、晶片、圖表頂部的數字、圖表、整體的各部分、量表、表格、手機版，以及不應複製的內容。
assets/dashboard.tsx	根據這些參考測量的儀表板套件：DashCard, Kpi, IconCircle, DeltaChip, StatusChip, TrendDot, CountBadge, Tabs, SeriesStat, StatColumns, Dashed, KeyValue, StackedBar, LegendGrid, Gauge, 表格的 TH/TR 類別, TooltipCard, PillMark, 用於 Recharts 的 chart props, ListaAlta（垂直卡片中的列表，按高度分頁）, Divergentes（相加與相減的項目）, Quadro100（每 100 個中的項目）, Colunas（浮動欄；瀑布圖與漏斗圖因難以理解而被否決）, useFitRows（可容納的行數）以及 useFitHeight（圖表高度由視窗剩餘空間決定；當上方卡片變大時會重新測量）。
assets/painel.tsx	地圖輔助工具：useMapColumns（地圖欄位寬度）與 FillMap（填滿整個空間的世界地圖）。
assets/ui.tsx	現成的基礎元件（Card, Section, IconBox, Chip, Pill, Button, BottomActions, ListRow, ListCard, StatCard, DateBlock, FillEmpty, InfoTip, NavLoading, Spinner, ThemeToggle, FitScreen）。請重複使用或調整，而不是重新發明。如果專案已有等效元件，則使用專案的。
scripts/lint-ui.mjs	node <skill>/scripts/lint-ui.mjs src：掃描已更改的程式碼（移動的懸停效果、省略號、彩色邊框、狹窄寬度、禁止的字體、會破壞其中一個主題的固定顏色、「—」、「 · 」、小寫、「標籤: 值」）。
scripts/check-ui.mjs	node <skill>/scripts/check-ui.mjs http://localhost:3000/rota --out=prints：在 320 與 390 px（行動版）以及瀏覽器實際可用區域中，於 1366×650、1536×730、1920×950（筆記型電腦與顯示器）以及 2560×960、2752×1100（21:9，Windows 125% 縮放）和 3440×1300（超寬螢幕 21:9）的尺寸下，於深色 和 淺色主題中拍攝截圖，並測量水平與垂直溢出（卡片超出第一屏底部邊緣或高於視窗）、看似重複的列表、拉伸的圖表以及過寬的清單行、「…」、相鄰卡片高度不同（也在無背景的包裝器內）、卡片內部有空白間隙或內容分散、網格不完整、無容器的圖示、移動的懸停效果、內部滾動、狹窄內容、字體、無游標指標的可點擊元素、幾乎對齊的卡片邊框、「i」氣球提示超出螢幕（逐個開啟）、行動版上的滾動條、過寬的表格行（任何重複行）、壓縮的文字、在行動版上換行的列表行標題或說明，以及空白或錯誤頁面（等待載入；如果資料未載入，則檢查無效）。每個發現都附帶尺寸與主題。專案需要安裝 Playwright；使用 --user/--pass 處理有密碼保護的頁面。

腳本是輔助工具：請檢查每個發現，最重要的是，開啟截圖並仔細查看。

1. 流程（造成最多返工的原因）

1. 只做被要求的內容。 未經明確要求，切勿移除、替換或「簡化」現有元素。如果提案要求刪除某些內容，請先詢問。如有疑問，請保留。
2. 尊重指定的斷點。 要求調整行動版：網頁版不變（使用 sm:/md: 來保留網頁版，反之亦然）。
3. 在發布前展示，查看所有尺寸。 在你說它已經足夠好之前，請開啟檢查中每個尺寸的截圖（包括 1366、1536 和 2752，表格會斷開，卡片會溢出），而不僅僅是 390 和 1920。委派給代理的工作也一樣：請親自檢查。在本地執行，在行動版（390px，並檢查 320px） 和網頁版（1366×650、1536×730 和 1920×950，瀏覽器實際可用區域），兩個主題，真正查看每張截圖，並且只有在獲得明確批准後才進行 commit/push/deploy。
4. 新畫面或重新設計：先處理資訊，再處理佈局。 遵循 references/informacao.md（並查看 references/padroes-aprovados.md 中的區塊以及 references/armadilhas.md 中的錯誤）：產品已知的庫存（包括舊畫面顯示的所有內容）、按緊急程度排序的使用者問題、優先級別、每個資訊的篩選器、位置地圖以及書面計畫。構圖衍生自該計畫。由你選擇構圖和調色盤（如果專案有品牌色則使用品牌色；否則使用 paletas.md 中與主題相符的調色盤）。不要為了讓使用者選擇而建立多個版本或畫面視圖。 建立一個，最好的那個，並用幾句話解釋為什麼每個東西都在那個位置。切勿從先前專案的骨架開始，也不要預設重複「4 個指標 + 卡片網格 + 列表」。
5. 兩次被拒絕的細節 = 並排選項。 僅當使用者已經兩次拒絕了同一個細節（例如晶片位置、字體）時，才在截圖中顯示該細節的 2 或 3 個變體。切勿用於整個畫面。
6. 在刪除或重建檔案後，重新啟動開發伺服器（或重新儲存 CSS），然後再執行檢查：Tailwind 可能會繼續提供舊的 CSS，而不包含新的類別。
7. 在每次截圖前，使用核對清單（第 10 節）進行審查。 如果沒有對稱性，則表示尚未準備好。

2. 字體排印

• 禁止使用（AI 感的字型）： Inter, Roboto, Arial, Helvetica, 將 system-ui 用作品牌字型, Geist, Poppins, Montserrat, Space Grotesk, Open Sans, Lato。
• 優秀且較少被 AI 使用的字型： Plus Jakarta Sans（首選且已獲批准）, Manrope, Onest, Figtree, Hanken Grotesk, Schibsted Grotesk, Instrument Sans, Albert Sans, Familjen Grotesk。對於強調標題，使用 Bricolage Grotesque。每個應用程式只使用一個字型家族。
• 數字使用 font-variant-numeric: tabular-nums（tabular-nums）。不要使用帶有切割或點狀零的等寬字型。
• 層級通過適度的粗細和大小來實現。上方的小標籤（12px，顏色較淡）和下方的值（16px，半粗體）。並排的值使用相同字體大小。不要使用巨大的彩色文字。
• 所有可見的文字以大寫開頭，包括單獨的縮寫（例如「Qui」、「Sex」）。在句子中間，請正常書寫：「Vs terça anterior」，而不是「Vs Ter anterior」。標題使用句子大小寫，切勿全部大寫。

3. 顏色與主題

• 永遠是兩個主題，淺色和深色。 每個應用程式從誕生起就同時擁有這兩個主題：遵循系統主題（prefers-color-scheme）並有一個切換按鈕（assets/ui.tsx 中的 ThemeToggle），切換選擇會被儲存。電子郵件和預覽也回應 prefers-color-scheme。沒有任何畫面可以僅存在於一個主題中。
• 顏色始終通過 token 使用（var(--card)、bg-card、text-muted-foreground）。不要在元件、圖表或 SVG 中使用 #000、#fff、bg-black、text-white 或單獨的十六進位碼：這會破壞另一個主題。
• 深色： 非常暗的背景（接近黑色），卡片高一個層級，邊框不明顯，文字接近白色。淺色： 非常淺的灰色背景，白色卡片，輕微邊框，文字接近黑色。兩者都應以同樣的細心對待，並在截圖中檢查。
• 調色盤不是固定的，但也不是隨意的。 不存在標準的「黑色 + 橙色」：請使用 references/paletas.md 中的完整調色盤（灰色、強調色、比例和系列色，這些顏色相互搭配，並已針對對比度和色盲進行驗證），根據主題選擇並顯示渲染結果。不要混合隨意顏色（某處的藍色、另一處的黃色、再另一處的紅色）。有品牌的專案應遵循其品牌色（例如 MegaLab 選擇了橙色）；只有當新顏色在兩個主題中與卡片的對比度至少達到 3:1，且色盲人士可以區分時，才能引入新顏色（如果代理有 dataviz 指南，請使用其驗證器）。
• 中性基底，顏色有目的性。 灰色約佔畫面的 90%。每個應用程式只有一個強調色（每個主題一個版本）。有序資料（大小、級別、範圍）使用單一顏色的比例（--seq-1..4），絕不使用灰色、藍色、黃色和紅色的彩虹。無序系列使用固定順序的 --cat-1..3。紅色/黃色警報僅用於真正的狀態，並附帶圖示和標籤。綠色永遠不應是品牌色，但可以出現在資料中：表示「改善」的變化晶片、良好狀態以及經過驗證的調色盤中類別系列 3 的顏色。沒有隨機的紫色，沒有棕色。
• 數字永不著色。 數值和標籤使用文字顏色；資料的顏色顯示在旁邊的小標記上（點、細條、帶有彩色細條的中性印章）。
• 改善和惡化的變化（如同使用者的參考文獻）：柔和的綠色晶片和柔和的紅色晶片，始終帶有箭頭，以供無法區分顏色的人使用（DeltaChip）。不變：灰色晶片。
• 相似的狀態（例如：錯了、困難、好、簡單）需要使用彼此明顯不同的顏色。
• 不要使用彩色邊框或光環來突出顯示卡片。僅使用顏色的柔和背景進行突出顯示（bg-primary/10）。
• 文字在兩個主題中都必須清晰可讀，包括圖例和點擊後的圖表工具提示。

4. 佈局與對稱性

• 網頁版使用全寬。 不要有置中的狹窄內容（頁面上的 max-w-* + mx-auto）。使用網格來填滿螢幕。
• 寬螢幕應增加欄數，而不是拉伸內容。 從 1920 px 以上以及超寬 21:9（2560 和 3440 px）開始，使用 3xl:（1920 px）和 4xl:（2560 px）來增加欄數，這些定義在 tokens.css 中；絕對不要使用 min-[1920px]:（在 Tailwind v4 中，它會輸給 lg:）；開啟之前隱藏的側面板（旁邊的詳細資訊、圖表旁邊的表格），並限制寬高比：時間圖表最多約 4:1，長條圖和地圖最多約 2.5:1，列表行最多約 720 px。請參閱 references/dashboards.md 第 4 節。
• 行動版優先。 舒適的側邊間距（16 px），不要擁擠，水平滾動的輪播要有呼吸空間，第一個項目上方要有空間。
• 符合螢幕高度。 內容在兩個方向上都適應視窗，而不僅僅是寬度。沒有任何固定尺寸的地圖、圖表、圖像或卡片超出第一屏的底部邊緣，或高於視窗（只有列表會繼續向下，頁面可以滾動）：地圖、圖表和大型圖像的高度受到視窗限制（max-h-[calc(100dvh-<header>)]、h-[min(…,60dvh)]、SVG 使用 preserveAspectRatio="xMidYMid meet" 且位於定義了高度的容器內）。切勿僅根據寬度來調整寬視覺元素的大小（w-full h-auto、aspect-[2/1]）：在寬顯示器或筆記型電腦上，它會向下溢出。第一屏（頁首、指標和主要區塊）應完全適合 390×844、1366×650、1536×730 和 1920×950 的尺寸（瀏覽器的實際可用區域，已減去工具列；整個螢幕不適合作為測量單位）。使用 assets/ui.tsx 中的 FitScreen。
• 畫面始終被填滿。 最後一個區塊會延伸到底部（flex-1）。不要有一半的畫面是空的：使用真實內容或視覺上的空狀態（容器中的圖示 + 1 行文字）。
• 對稱性是強制性的：
  • 並排的卡片必須具有相同的高度（items-stretch、h-full），並且內部內容（圖表、表格）會隨之增長並佔滿整個高度；
  • 左側和右側的文字行數相同；
  • 被網格拉伸的卡片內部不應有空白間隙：固定高度的列表行，並且區塊（標題 + 行）在垂直方向上居中，絕對不要使用 justify-around/justify-between 來分散行；可比較的欄（A 對 B）具有相同的行高，以便行對齊（請參閱 references/armadilhas.md 中的「Cartão que estica」）；
  • 網格行必須完整（不能有 3 + 1 剩餘）；
  • 在同一欄中，項目和晶片必須具有相同的寬度；
  • 欄的

...

[因輸入內容被截斷，此為不完整的翻譯]