Communitygithub.com

ulasalyesil/personal-website-v2

根據 components.build 規範,建立現代化、可組合且無障礙的 React UI 元件。適用於建立、審查或重構元件庫、設計系統或任何可重複使用的 UI 元件。觸發條件為涉及元件 API、組合模式、無障礙性、樣式系統或 TypeScript props 的任務。

personal-website-v2 是什麼?

這項技能提供了一套完整的指導方針,用於建構現代化、可組合且無障礙的 React UI 元件,總共涵蓋 16 個規則類別,從核心原則到發佈策略一應俱全。由 Hayden Bleasel 和 shadcn 共同撰寫,內容基於 components.build 規範。 此技能適用於所有支援 AI 輔助開發的平台,例如 Claude Code、Cursor 和 Codex。當開發者建立新的 React 元件、設計元件 API、實作無障礙功能(鍵盤導覽、ARIA)、建構組合式架構、使用 Tailwind CSS 和 CVA 進行樣式設計,或將元件發佈到 npm 或註冊表時,都能透過這套規範獲得即時的指引。 其核心原則包括:偏好組合而非配置、將無障礙性視為預設要求、每個元件只包裝一個 HTML 元素、擴展原生的 HTML 屬性、匯出 TypeScript 型別,以及使用 cn() 工具函數進行智慧樣式合併。 規則類別依優先順序排列,涵蓋概觀、原則、定義、組合、無障礙性、狀態管理、TypeScript 型別、多型、As-Child 模式、資料屬性、樣式設計、設計符記、文件、註冊表、npm 和市場平台。每個類別都有詳細的說明、不正確與正確的程式碼範例,以及最佳實踐。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ulasalyesil/personal-website-v2/tree/HEAD/.agents/skills/components-build

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Components.build 規範

關於建立現代化、可組合且無障礙 UI 元件的全面指導方針。包含 16 個規則類別,從核心原則到發佈策略,由 Hayden Bleasel 和 shadcn 共同撰寫。

何時套用

在以下情況參考這些指導方針:

  • 建立新的 React 元件或元件庫
  • 設計元件 API 和 prop 介面
  • 實作無障礙功能(鍵盤、ARIA、焦點管理)
  • 建構可組合的元件架構
  • 使用 Tailwind CSS 和 CVA 進行元件樣式設計
  • 將元件發佈至註冊表或 npm

依優先順序排列的規則類別

優先順序類別重點前綴
1概觀規範範圍與目標overview
2原則核心設計理念principles
3定義常用術語definitions
4組合分解複雜元件composition
5無障礙性鍵盤、螢幕報讀軟體、ARIAaccessibility
6狀態可控/非可控模式state
7型別TypeScript props 與介面types
8多型使用 as prop 切換元素polymorphism
9As-ChildRadix Slot 組合模式as-child
10資料屬性data-state 和 data-slotdata-attributes
11樣式設計Tailwind CSS、cn 工具、CVAstyling
12設計符記CSS 變數與主題設定design-tokens
13文件元件文件documentation
14註冊表元件註冊表registry
15NPM發佈至 npmnpm
16市場平台元件市場marketplaces

快速參考

1. 概觀

  • overview - 規範範圍、目標與理念

2. 原則

  • principles - 可組合性、無障礙性、可自訂性、透明度

3. 定義

  • definitions - 常用術語(原始、複合、無頭等)

4. 組合

  • composition-root - 使用 Context 管理共享狀態的根元件
  • composition-item - 項目包裝元件
  • composition-trigger - 互動觸發元件
  • composition-content - 內容顯示元件
  • composition-export - 命名空間匯出模式

5. 無障礙性

  • accessibility-semantic-html - 使用適當的 HTML 元素
  • accessibility-keyboard - 完善的鍵盤導覽支援
  • accessibility-aria - 正確的 ARIA 角色、狀態與屬性
  • accessibility-focus - 焦點管理與還原
  • accessibility-live-regions - 螢幕報讀軟體提示
  • accessibility-contrast - 顏色對比度要求

6. 狀態

  • state-uncontrolled - 內部狀態管理
  • state-controlled - 外部狀態委派
  • state-controllable - 使用 useControllableState 支援兩種模式

7. 型別

  • types-extend-html - 擴展原生 HTML 屬性
  • types-export - 為消費者匯出 prop 型別
  • types-single-element - 一個元件包裝一個元素

8. 多型

  • polymorphism-as-prop - 變更渲染的 HTML 元素類型
  • polymorphism-typescript - 型別安全的多型元件
  • polymorphism-defaults - 語意元素的預設值

9. As-Child

  • as-child-slot - 使用 Radix Slot 進行 prop 合併
  • as-child-composition - 與子元件組合

10. 資料屬性

  • data-attributes-state - 使用 data-state 設定狀態樣式
  • data-attributes-slot - 使用 data-slot 定位子元件

11. 樣式設計

  • styling-cn-utility - 合併 clsx 和 tailwind-merge
  • styling-order - 基礎 → 變體 → 條件式 → 使用者覆寫
  • styling-cva - 使用 Class Variance Authority 定義變體
  • styling-css-variables - 使用 CSS 變數實現動態值

12. 設計符記

  • design-tokens-css-variables - 將符記定義為 CSS 變數
  • design-tokens-theming - 支援淺色/深色模式與主題

13. 文件

  • documentation-props - 使用 JSDoc 記錄所有 props
  • documentation-examples - 提供使用範例

14. 註冊表

  • registry-structure - 註冊表檔案結構
  • registry-schema - 元件元資料架構

15. NPM

  • npm-package-json - 套件設定
  • npm-exports - 模組匯出

16. 市場平台

  • marketplaces-distribution - 元件發佈策略

如何使用

閱讀個別的規則檔案以取得詳細說明和程式碼範例:

rules/composition/SKILL.md
rules/accessibility/SKILL.md
rules/styling/SKILL.md

每個規則檔案包含:

  • 為何重要的簡短說明
  • 包含說明的錯誤程式碼範例
  • 包含說明的正確程式碼範例
  • 最佳實踐與常見陷阱

完整彙編文件

如需包含所有規則的完整指南,請參閱:AGENTS.md

關鍵原則

  1. 組合優先於設定 - 將元件分解為可組合的子元件
  2. 無障礙性為預設 - 這是必要條件,而非事後補救
  3. 單一元素包裝 - 每個元件包裝一個 HTML 元素
  4. 擴展 HTML 屬性 - 務必擴展原生元素 props
  5. 匯出型別 - 讓 prop 型別可供消費者使用
  6. 支援兩種狀態模式 - 可控與非可控
  7. 智慧型樣式合併 - 使用 cn() 工具函數搭配 tailwind-merge

作者

共同撰寫:

改編為 AI 技能:

基於 components.build 規範。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ulasalyesil/personal-website-v2

Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.

ulasalyesil/personal-website-v2

Conduct design interviews, generate five distinct UI variations in a temporary design lab, collect feedback, and produce implementation plans. Use when the user wants to explore UI design options, redesign existing components, or create new UI with multiple approaches to compare.

ulasalyesil/personal-website-v2

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.

ulasalyesil/personal-website-v2

Design and implement microinteractions, motion design, transitions, and user feedback patterns. Use when adding polish to UI interactions, implementing loading states, or creating delightful user experiences.

ulasalyesil/personal-website-v2

This skill is for interface design — dashboards, admin panels, apps, tools, and interactive products. NOT for marketing design (landing pages, marketing sites, campaigns).

ulasalyesil/personal-website-v2

Best practices and example-driven guidance for building SwiftUI views and components. Use when creating or refactoring SwiftUI UI, designing tab architecture with TabView, composing screens, or needing component-specific patterns and examples.

ulasalyesil/personal-website-v2

UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 9 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient. Integrations: shadcn/ui MCP for component search and examples.

ulasalyesil/personal-website-v2

Conduct WCAG 2.2 accessibility audits with automated testing, manual verification, and remediation guidance. Use when auditing websites for accessibility, fixing WCAG violations, or implementing accessible design patterns.

ulasalyesil/personal-website-v2

Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".

ulasalyesil/personal-website-v2

Enforces an opinionated UI baseline to prevent AI-generated interface slop.

ulasalyesil/personal-website-v2

Ship correct, complete metadata.

ulasalyesil/personal-website-v2

Survey any codebase as a senior advisor and produce prioritized, self-contained implementation plans for OTHER models/agents to execute. Strictly read-only on source code — never implements, fixes, or refactors anything itself. Use when asked to audit a codebase, find improvement opportunities (bugs, security, performance, test coverage, tech debt, migrations, DX), suggest features or where to take the project next (roadmap, product direction), or generate handoff plans for another agent to implement.

ulasalyesil/personal-website-v2

Defines the product's objects, relationships, states, and vocabulary independently of any interface — the most load-bearing layer

ulasalyesil/personal-website-v2

Maps domain concepts, terminology conflicts, and bounded contexts — produces a noun harvest for the conceptual model layer

ulasalyesil/personal-website-v2

Maps interaction structure and flow — produces breadboard notation with edge cases, failure paths, and open decisions

ulasalyesil/personal-website-v2

Framework orientation for Layers of Product Design — load this first; provides the context all other skills depend on

ulasalyesil/personal-website-v2

User research planning and synthesis at the observed behaviour layer — produces candidate job stories with confidence ratings

ulasalyesil/personal-website-v2

Diagnostic audit across all seven layers — identifies the bottleneck layer and recommends where to focus

ulasalyesil/personal-website-v2

Connects user opportunities to business outcomes and solution bets — produces a strategy tree and prioritised experiments

ulasalyesil/personal-website-v2

Audits existing surface against lower-layer decisions and produces a surface decision inventory — vocabulary, object consistency, completeness, feedback, hierarchy, accessibility

相關技能