Skip to content
Back to search

component-catalog

替網頁專案導入一套「元件總表」管理方式:每個畫面物件(頭像、分隔線、空狀態、按鈕外觀…)定義共用介面,每種風格或主題各一份實作、缺的自動用基本款;用腳本從程式碼自動產生總表,過期就讓檢查失敗;再把「做畫面前先查總表、用現成元件」寫進給 AI 的專案說明。使用時機:使用者要建立或整理元件庫、設計系統、主題/換膚/多品牌系統;抱怨素材做了沒人用、AI 或同事不知道有現成元件、同一個東西每頁各畫一份、換主題要改很多頁;問「元件齊了嗎」「哪些主題還沒補」「把不足的補齊」;或開新的前端專案想先把元件管理打好基礎。即使使用者沒說「總表」「插槽」,只要是在處理前端元件怎麼組織、怎麼讓人和 AI 找得到、怎麼盤點缺口,就用這個 skill。單一風格的網站也適用。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/twinklestars1029--component-catalog/badge.svg)](/listings/twinklestars1029--component-catalog)

HTML

<a href="/listings/twinklestars1029--component-catalog"><img src="/api/listings/twinklestars1029--component-catalog/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Claude Code**:把 `component-catalog` 資料夾複製到 `~/.claude/skills/`(Windows 是 `C:\Users\<你的帳號>\.claude\skills\`)。

**claude.ai**:在技能設定上傳 `component-catalog.skill` 檔。

裝好後不用特別呼叫。你提到下面這類需求時,Claude 會自動使用它。

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 118 lines
  1. ---
  2. name: component-catalog
  3. description: 替網頁專案導入一套「元件總表」管理方式:每個畫面物件(頭像、分隔線、空狀態、按鈕外觀…)定義共用介面,每種風格或主題各一份實作、缺的自動用基本款;用腳本從程式碼自動產生總表,過期就讓檢查失敗;再把「做畫面前先查總表、用現成元件」寫進給 AI 的專案說明。使用時機:使用者要建立或整理元件庫、設計系統、主題/換膚/多品牌系統;抱怨素材做了沒人用、AI 或同事不知道有現成元件、同一個東西每頁各畫一份、換主題要改很多頁;問「元件齊了嗎」「哪些主題還沒補」「把不足的補齊」;或開新的前端專案想先把元件管理打好基礎。即使使用者沒說「總表」「插槽」,只要是在處理前端元件怎麼組織、怎麼讓人和 AI 找得到、怎麼盤點缺口,就用這個 skill。單一風格的網站也適用。
  4. ---
  5. # 元件總表(component-catalog)
  6. ## 這套方法解決什麼
  7. 前端專案常見三個問題:
  8. 1. **素材做了沒人用**:設計師畫好、工程師也寫好,但做新頁面的人(或 AI)不知道它存在,又自己畫了一份。
  9. 2. **同一個物件到處各寫一份**:換風格或改設計時,要一頁一頁找。
  10. 3. **不知道還缺什麼**:哪個風格少了哪個元件,只能靠記憶。
  11. 解法是三件事一起做:
  12. - **物件 × 風格的格子(插槽)**:每個物件定義一個共用介面,每個風格各寫一份實作;某風格沒有就自動用基本款。頁面只寫一次,換風格時自動換外觀。
  13. - **自動產生的總表**:腳本從程式碼產生一張表,列出每格是「專屬/用基本款/不畫」和用在哪裡,並標出「還沒有地方使用」的物件。手寫的表一定會過時,過時的表比沒有更誤導,所以要自動產生,過期就讓檢查失敗。
  14. - **給 AI 的規則**:寫進專案說明檔(例如 CLAUDE.md),讓 AI 每次做畫面前先查總表、用現成的,找不到就問。
  15. 只有一種風格的網站也適用:格子只有一欄,總表仍然告訴大家有哪些元件、用在哪、哪些沒人用。
  16. ## 名詞
  17. - **物件**:畫面上會重複出現、值得統一的東西,例如頭像、分隔線、空狀態、區塊標題、按鈕外觀、裝飾花飾。一般的按鈕、輸入框若只是換顏色,用設計變數就好,不必做成物件。
  18. - **風格**:主題、品牌或換膚選項。單一風格的專案只有一個「基本款」。
  19. - **基本款**:每個物件都必須有的預設實作,也是其他風格缺件時的備用。
  20. - **插槽**:物件的共用介面加上「依目前風格取出那一份實作」的機制。
  21. - **總表**:自動產生的 Markdown 檔,是人和 AI 查元件的入口。
  22. ## 先判斷要做哪一件事
  23. | 使用者的情況 | 走哪個流程 |
  24. |---|---|
  25. | 開新專案,想先把元件管理打好 | A. 新專案導入 |
  26. | 專案已經有一堆元件,想整理、建總表 | B. 既有專案盤點導入 |
  27. | 已經導入,要做新畫面 | C. 日常做畫面 |
  28. | 問「齊了嗎」「哪些還沒補」「把不足的補齊」 | D. 盤點缺口(讀 `references/gap-audit.md`) |
  29. A、B 會改專案結構,動手前先把計畫(要建哪些檔案、搬哪些元件)講給使用者聽,等同意再做。
  30. ## A. 新專案導入
  31. 1. **問清楚兩件事**:用什麼框架;有沒有(或之後會不會有)多種風格。其他細節照下面的預設做。
  32. 2. **建資料夾**:`src/ui/variants/base/`,有多種風格再加 `src/ui/variants/<風格 id>/`。各框架的插槽寫法看 `references/stacks.md`,只讀使用者用的那一節。
  33. 3. **先放兩三個真的會用到的物件**,例如頭像、空狀態、分隔線。不要一開始就做一整套;物件應該在第一次被需要時才加。
  34. 4. **複製設定檔**:把 `assets/component-catalog.config.example.json` 複製到專案根目錄,改名為 `component-catalog.config.json`,改成實際的路徑、風格、物件。每個物件寫中文名稱和用途,用途要寫「用在哪種情況、什麼時候不用」,AI 才判斷得出該不該用。
  35. 5. **複製腳本並接上指令**:把 `scripts/catalog.mjs` 複製到專案(例如 `scripts/catalog.mjs`),在 `package.json` 加:
  36. ```json
  37. "catalog": "node scripts/catalog.mjs",
  38. "catalog:check": "node scripts/catalog.mjs --check"
  39. ```
  40. 再把 `npm run catalog:check` 接進現有的測試或 CI 指令(例如 `"test": "vitest run && npm run catalog:check"`)。這一步是整套方法的保險:沒有它,總表遲早會過時。
  41. 6. **寫進給 AI 的規則**:把 `assets/agent-rules.md` 的內容貼進專案說明檔(Claude Code 用 `CLAUDE.md`;沒有就新建),換掉 `<…>`。單一風格的專案刪掉提到風格的句子。
  42. 7. **產生並確認**:跑 `npm run catalog`,打開總表給使用者看;再跑 `npm run catalog:check` 確認通過。
  43. ## B. 既有專案盤點導入
  44. 既有專案的元件通常散在各處。目標是**先把現況照實列出來**,不要一次重構全部。
  45. 1. **找出候選物件**:搜尋重複出現的畫面片段,例如多個頁面各自畫的空狀態、手寫的 `<hr>`、相同的 SVG、名稱相近的元件(`UserAvatar`、`ProfilePic`)。也找「做了但沒被 import」的元件檔,它們就是「做了沒人用」的素材。
  46. 2. **回報清單給使用者**:每個候選寫出它在哪些檔案出現幾次、建議合併成哪個物件。等使用者挑選要先納管哪些。
  47. 3. **一次只搬幾個**:照 A 的第 2 步建資料夾,把挑中的物件搬進 `variants/base/`(有多種風格的話,各風格的版本搬進各自資料夾),頁面改成透過插槽取用。每搬一個就跑一次專案的測試。
  48. 4. **還沒搬的不要硬列**:總表只列已經在插槽結構裡的物件。尚未搬的候選寫在回報或待辦裡,之後再處理。
  49. 5. 照 A 的第 4~7 步建設定檔、腳本、規則並產生總表。
  50. ## C. 日常做畫面
  51. 已導入的專案,規則在專案說明檔裡。做畫面時:
  52. 1. 先讀總表。需要的物件已經有了就用插槽取用,不要在頁面裡再畫一份,也不要在頁面裡寫「如果是某風格就…」的判斷。
  53. 2. 總表標「還沒有地方使用」的物件,是等著被放進畫面的素材。新畫面有合適的位置就用上。
  54. 3. 需要的物件不存在:先問使用者,不要自己新增插槽。新增會改到所有風格,屬於設計決定。
  55. 4. 新增或改了物件、風格、使用處之後,重新產生總表;新增物件記得在設定檔補中文名稱與用途。
  56. ## D. 盤點缺口
  57. 讀 `references/gap-audit.md`。重點:
  58. - 總表的「用基本款」不一定是缺,要回頭查設計稿才知道。
  59. - **說「設計稿沒畫」之前,所有設計檔都要查過**,包括各頁畫板,不只元件包。
  60. - 缺口分四類:做了沒用、有設計沒程式、連設計都沒有、有素材沒位置。照這個順序排,交給使用者決定先做哪批。
  61. ## 腳本:`scripts/catalog.mjs`
  62. 只用 Node 內建模組,不需要安裝套件。它只看檔案,不執行專案程式:
  63. - `<variantsDir>/<風格>/<物件><副檔名>` 存在 → 專屬;不存在 → 用基本款。
  64. - 檔案內容符合 `nullPattern`(例如整個元件只回傳 `null`)→ 不畫。
  65. - 原始碼裡出現 `<物件名`、`<物件-kebab` 或 `.物件名` → 算一個使用處。
  66. - 風格資料夾裡有、設定檔沒登記的大寫開頭檔案 → 印出提醒,避免素材漏列。
  67. - 基本款缺物件、風格資料夾不存在 → 直接失敗。
  68. 設定檔欄位:
  69. | 欄位 | 必填 | 說明 |
  70. |---|---|---|
  71. | `output` | 是 | 總表要寫到哪裡 |
  72. | `variantsDir` | 是 | 風格資料夾的上層 |
  73. | `baseVariant` | 是 | 基本款的風格 id |
  74. | `variants` | 是 | `[{ id, name }]`,表格欄位的順序 |
  75. | `objects` | 是 | `{ 物件名: { name, use, example? } }`,表格列的順序 |
  76. | `title` | 否 | 總表標題 |
  77. | `extensions` | 否 | 認哪些副檔名,預設 `.tsx .jsx .ts .js .vue .svelte` |
  78. | `sourceDirs` | 否 | 去哪裡找使用處,預設 `["src"]` |
  79. | `nullPattern` | 否 | 認出「不畫」的正規表示式 |
  80. | `shared` | 否 | `[{ name, how }]`,不是物件、只換數值的共用設定(顏色、圓角、字型) |
  81. 如果專案結構特殊、腳本的規則不夠用(例如物件不是一檔一個),可以改腳本,但保留兩個原則:總表從程式碼產生、過期時檢查會失敗。
  82. ## 原則與理由
  83. - **總表自動產生,不手寫**:手寫的表一定會和程式脫節,脫節的表會讓 AI 和人用錯元件。
  84. - **一個物件第一次被需要時才加**:預先做一整套,多半會變成沒人用的素材,正是這套方法要解決的問題。
  85. - **找不到合適的就問,不要自己新增**:新增插槽會影響所有風格,是設計決定,不是實作細節。
  86. - **先查設計稿再說「沒有」**:設計常分散在好幾個檔案。誤判「沒畫」會讓使用者以為要先補設計,白白延後。
  87. - **裝飾類素材要有指定位置才放**:沒說放哪的素材,放錯地方比不放更糟。
README.md · README · 102 lines
  1. # component-catalog:讓人和 AI 都找得到現成元件
  2. 這是一個給 Claude 用的 skill(技能包)。它幫網頁專案建立一套元件管理方式:每個畫面物件只寫一份,自動產生一張「元件總表」,並讓 AI 做畫面前先查表、用現成的。
  3. 單一風格的網站、有多種主題或換膚的網站都適用。React、Vue、Svelte,或只有 CSS 的專案都能用。
  4. ## 它解決什麼問題
  5. - **素材做了沒人用**:設計師畫好、工程師也寫好了,但做新頁面的人或 AI 不知道它存在,又自己畫了一份。
  6. - **同一個東西到處各寫一份**:頭像、分隔線、「沒有資料」的畫面,每頁長得都有點不一樣。要改設計時,得一頁一頁找。
  7. - **不知道還缺什麼**:哪個主題少了哪個元件,只能靠記憶。
  8. ## 它怎麼做
  9. 1. **每個物件一份共用介面,每種風格各一份實作**:頁面只寫一次 `<Avatar />`,換主題時外觀自動跟著換。某個主題沒有專屬版本,就自動用基本款。
  10. 2. **用腳本從程式碼自動產生總表**:手寫的清單一定會過時,所以總表由腳本產生。程式改了、總表沒重新產生,測試就會失敗。
  11. 3. **把規則寫進給 AI 的專案說明**:例如 Claude Code 的 `CLAUDE.md`,規則是做畫面前先查總表、用現成元件、找不到合適的先問人,不要自己新增。
  12. ## 總表長什麼樣
  13. 腳本產生的 `CATALOG.md` 開頭會有一張一覽表:
  14. | 物件 | 基本款 | 森林 | 復古 | 使用處 |
  15. |---|---|---|---|---|
  16. | 頭像 `Avatar` | 專屬 | 專屬 | 專屬 | 1 處 |
  17. | 分隔線 `Divider` | 專屬 | 專屬 | 用基本款 | 1 處 |
  18. | 空狀態 `EmptyState` | 專屬 | 專屬 | 用基本款 | 1 處 |
  19. | 點綴 `Sparkle` | 不畫 | 專屬 | 不畫 | **還沒有地方使用** |
  20. - **專屬**:這個主題有自己的版本。
  21. - **用基本款**:沒有專屬版本,自動用基本款。
  22. - **不畫**:這個主題刻意不畫這個物件。
  23. - **還沒有地方使用**:做好了卻沒放進任何畫面,是最該先處理的素材。
  24. 一覽表下面,每個物件各有一節:用途、每個主題的程式檔連結、目前用在哪些檔案。
  25. 只有一種風格的網站,表格只會有「物件」和「使用處」兩欄。
  26. ## 安裝
  27. **Claude Code**:把 `component-catalog` 資料夾複製到 `~/.claude/skills/`(Windows 是 `C:\Users\<你的帳號>\.claude\skills\`)。
  28. **claude.ai**:在技能設定上傳 `component-catalog.skill` 檔。
  29. 裝好後不用特別呼叫。你提到下面這類需求時,Claude 會自動使用它。
  30. ## 怎麼用
  31. 直接用平常的話說就好,例如:
  32. | 你的情況 | 可以這樣說 |
  33. |---|---|
  34. | 開新專案,想先打好基礎 | 「我在做一個 React 部落格,之後想要日間和復古兩種主題,幫我把元件管理建立起來。」 |
  35. | 舊專案元件很亂 | 「我們的元件越來越亂,有些做了沒人用,幫我盤點,先給我看結果再動手。」 |
  36. | 想知道還缺什麼 | 「森林和復古兩個主題各還缺哪些元件?設計稿在 design/ 資料夾。」 |
  37. | 已經導入,要做新頁面 | 照常請它做畫面就好,它會先查總表。 |
  38. Claude 改動專案結構之前,會先說明要建哪些檔案、搬哪些元件。既有專案會先盤點,請你挑要先整理哪幾個,一次只搬幾個。
  39. ## 需要什麼
  40. - **Node.js 18 以上**:總表腳本只用 Node 內建功能,不用安裝任何套件。
  41. - **專案結構**:每個風格一個資料夾,每個物件一個檔案,例如 `src/ui/variants/base/Avatar.tsx`。Claude 導入時會幫你建好。
  42. ## 檔案內容
  43. ```
  44. component-catalog/
  45. ├── SKILL.md 給 Claude 的主要說明:四種情境的做法
  46. ├── scripts/catalog.mjs 總表產生腳本(加 --check 只檢查是否過期)
  47. ├── assets/
  48. │ ├── component-catalog.config.example.json 設定檔範本
  49. │ └── agent-rules.md 貼進 CLAUDE.md 的規則範本
  50. └── references/
  51. ├── stacks.md React、Vue、Svelte、純 CSS 的寫法
  52. └── gap-audit.md 盤點缺口與補齊順序的做法
  53. ```
  54. 設定檔每個欄位的說明,寫在 `SKILL.md` 的「腳本」一節。
  55. ## 測試結果
  56. 我們用三個情境,分別讓 Claude 在「有這個 skill」和「沒有這個 skill」的情況下做同一件事,再逐項檢查結果:
  57. | 情境 | 有 skill | 沒有 skill |
  58. |---|---|---|
  59. | 替新的 React 專案導入 | 6/6 | 1/6 |
  60. | 盤點已導入專案的主題缺口 | 8/8 | 8/8 |
  61. | 盤點單一風格的舊專案並提出計畫 | 8/8 | 6/8 |
  62. 沒有這個 skill 時,Claude 也會做共用元件,但清單多半是手寫的,不會自動產生,也不會接進測試,規則裡也少了「找不到先問」。第二個情境的專案本來就已經導入總表,所以兩組分不出差別。
  63. ## 限制
  64. - 腳本只看檔案名稱和內容,不執行程式。物件必須一個檔案一個,檔名就是物件名稱。
  65. - 「使用處」是用文字比對找出來的,例如找 `<Avatar` 或 `.Avatar`。用字串動態取用元件時會漏算,在設定檔的用途說明裡寫清楚取用方式即可。
  66. - 只有 CSS、沒有元件框架的專案,「使用處」欄只能當參考。
  67. - 專案結構特殊時可以修改腳本,但請保留兩個原則:總表從程式碼產生,過期時檢查會失敗。
  68. ## 授權
  69. MIT 授權,全文見 [LICENSE](LICENSE)。可以自由使用、修改、商用,只要保留原本的授權聲明。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.