Community코딩 & 개발github.com

react-components

의미론적이고 구성된 마크업 우선 React 컴포넌트 작성 — 의미론적 HTML 요소, 간결한 명칭의 컴포넌트 조합으로 이루어진 화면, 사실만 저장하고 나머지는 파생하는 얇은 Hook의 상태와 효과, 그리고 React 외부에 유지되는 비즈니스 로직(business-logic 스킬 참조). React 컴포넌트, Hook 또는 화면을 작성, 리뷰 또는 리팩토링할 때, JSX가 div와 클래스 문자열 투성이일 때, 컴포넌트가 return 앞에 긴 state와 effect를 가지고 있을 때, 또는 로직이 컴포넌트에 얽혀 있을 때 사용합니다.

react-components란 무엇인가요?

이 스킬은 의미론적이고, 구성 가능하며, 마크업을 우선시하는 React 컴포넌트를 작성하기 위한 포괄적인 가이드입니다. HTML5 의미론적 요소(예: main, header, section, button)를 사용하여 접근성과 명확성을 보장하는 방법을 강조합니다. 핵심 원칙은 화면을 이름 있는 컴포넌트(예: CatalogHeader, ProductRow)로 구성하여, 화면의 JSX가 마치 제품에 대한 개요처럼 읽히도록 하는 것입니다. 또한, 비즈니스 로직을 React 외부의 순수 함수로 분리하고, Hook을 얇게 유지하여 외부에서 도착한 사실만 저장하고 나머지는 렌더링 중에 파생하도록 권장합니다. 이 스킬은 상호 배타적인 뷰를 위한 판별 유니온(discriminated union), 자식은 보고하고 부모는 결정하는 패턴, 반복되는 마크업의 조기 추출을 다룹니다. 모든 규칙에는 설명을 위한 예제가 포함되어 있으며, 올바른 접근성, 유지보수성 및 테스트 가능성을 위한 실용적인 조언을 제공합니다.

지원 대상~Claude Code~Codex CLI~Cursor
Part ofReact
npx skills add https://github.com/tosinamuda/skills/tree/main/react-components

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

React 컴포넌트: 의미론적, 구성된, 마크업 우선

화면은 사람과 스크린 리더 모두가 그것이 무엇으로 구성되어 있는지 읽을 수 있어야 합니다. 어떤 프로젝트에서든 React 컴포넌트를 작성하거나 변경할 때 다음 규칙을 적용하세요.

  1. 요소는 자신이 무엇인지 말합니다. main, header, footer, nav, section, search, ul/li, button, time, form을 사용하세요. div 또는 span은 레이아웃이나 스크롤을 위해 존재하는 상자에만 사용합니다.
    // 이렇게 하지 마세요: 모든 상자가 div이므로 스크린 리더는 긴 텍스트 덩어리를 듣게 되고,
    // "button"은 Tab으로 접근하거나 Enter로 누를 수 없습니다.
    <div className="page">
      <div className="top">
        <span className="updated">10:42</span>
        <div className="search"><input placeholder="검색" /></div>
      </div>
      <div className="group">
        <div className="group-name">과일</div>
        <div className="items">
          <div className="item" onClick={add}>사과</div>
        </div>
      </div>
    </div>
    
    // 이렇게 하세요: 각 요소가 자신이 무엇인지 말하므로 랜드마크, 목록 및 버튼이 자동으로 제공됩니다.
    <main>
      <header>
        <time dateTime="10:42">10:42</time>
        <search><input type="search" aria-label="제품 검색" /></search>
      </header>
      <section aria-labelledby="fruit">
        <h2 id="fruit">과일</h2>
        <ul>
          <li><button type="button" onClick={add}>사과</button></li>
        </ul>
      </section>
    </main>
    
    각 선택이 주는 이점: main과 header는 스크린 리더가 페이지의 부분 간에 이동할 수 있게 합니다; h2가 있는 section은 영역의 이름을 지정합니다; ul/li는 "목록, 5개 항목"을 말합니다; button은 추가 코드 없이 Tab으로 도달하고 Enter 및 Space로 누를 수 있습니다; time과 search는 해당 콘텐츠가 무엇인지 말합니다. 아무 의미도 없는 곳(예: 목록을 옆으로 스크롤하는 상자)에는 div를 유지하세요.
  2. 화면은 이름 있는 부분의 구성입니다. 화면의 JSX는 제품 자체의 용어로 된 화면의 개요처럼 읽힙니다: 사람이 가리킬 각 부분에 대해 하나의 이름 있는 컴포넌트가 있습니다. 각 부분은 의미론적 요소와 클래스를 소유하는 작은 컴포넌트이므로 화면 자체에는 원시 HTML 태그나 클래스 문자열이 없습니다. 화면을 읽으면 화면에 무엇이 있는지 알 수 있습니다; 부분을 열면 어떻게 보이는지 알 수 있습니다.
    // 이렇게 하지 마세요: 화면은 태그와 클래스의 트리이며, 각 상자가 무엇인지 파악해야 합니다.
    <div className="flex h-screen flex-col gap-5 pt-7">
      <div className="flex items-center gap-3 px-8">
        <span className="text-gray-500">쇼핑몰</span>
        <span className="font-semibold">{storeName}</span>
      </div>
      <div className="min-h-0 flex-1 overflow-y-auto">
        {categories.map((c) => (
          <div key={c.name} className="flex flex-col gap-3">
            <div className="text-2xl font-semibold">{c.name}</div>
            <div className="flex gap-6 overflow-x-auto">{/* 상품 카드 */}</div>
          </div>
        ))}
      </div>
      <button className="absolute bottom-2 left-8 rounded-full" onClick={onBack}>←</button>
    </div>
    
    // 이렇게 하세요: 화면은 그 자체가 무엇인지에 따라 이름이 붙여진 부분들입니다.
    <CatalogLayout heading="제품">
      <CatalogHeader>
        <ShopName />
        <StoreName name={storeName} />
      </CatalogHeader>
      <CategoryList categories={categories} onAdd={add} />
      <BackButton label="매장으로 돌아가기" onBack={onBack} />
    </CatalogLayout>
    
    // 각 부분은 자체 요소와 클래스를 한 번만 보유합니다.
    function CatalogHeader({ children }: { children: ReactNode }) {
      return <header className="flex items-center gap-3 px-8">{children}</header>;
    }
    
    사람이 그것을 뭐라고 부를 수 있을 때(예: "헤더", "제품 행", "뒤로 가기 버튼") 부분에 이름을 붙일 가치가 있습니다. 간격을 위해서만 존재하는 래퍼는 화면이 아닌 그것이 필요한 부분 내부에 유지됩니다.
  3. 2학년생도 추측할 수 있는 이름. 사물에 대한 평이한 단어를 사용하세요: Layout, Header, Row, Card, List, Panel, Button, Margin. 제품의 사용자가 그 단어를 사용하지 않는 한 은유나 업계 전문 용어(Frame, Rail, Strip, Gutter, Chrome, Shell)는 사용하지 마세요. 테스트: 코드를 한 번도 본 적이 없는 사람이 <ProductRow>가 무엇을 그리는지 말할 수 있어야 합니다.
    // 이렇게 하지 마세요: 신규자가 해독해야 하는 은유와 전문 용어.
    <PageFrame><TopRail /><ProductStrip gutter={GUTTER} /></PageFrame>
    
    // 이렇게 하세요: 각 사물에 대한 평이한 단어.
    <PageLayout><PageHeader /><ProductRow margin={LEFT_MARGIN} /></PageLayout>
    
  4. 마크업 우선. 컴포넌트의 본문은 JSX입니다. return 앞에 몇 줄 이상의 state, effect 또는 파생이 있는 경우 이를 모델링하는 이름의 Hook(useProductSearch)으로 이동하고, 이 Hook은 사실과 액션을 반환합니다.
    // 이렇게 하지 마세요: 무엇이 그려지는지 보기 전에 수십 줄의 state와 effect가 있습니다.
    function CatalogScreen({ onAdd }: Props) {
      const [products, setProducts] = useState<Product[] | null>(null);
      const [query, setQuery] = useState("");
      const [adding, setAdding] = useState<string | null>(null);
      useEffect(() => { /* 제품 가져오기, 마운트 해제 방지 */ }, []);
      const categories = useMemo(() => /* 필터링 후 그룹화 */, [products, query]);
      const add = (p: Product) => { /* adding 설정, onAdd 호출, catch */ };
      // ... 30줄 더 ...
      return <CatalogLayout>...</CatalogLayout>;
    }
    
    // 이렇게 하세요: 모델링하는 대상의 이름을 가진 하나의 Hook, 그 다음 JSX.
    function CatalogScreen({ onAdd }: Props) {
      const search = useProductSearch({ onAdd });
      return (
        <CatalogLayout>
          <CategoryList categories={search.categories} onAdd={search.add} />
        </CatalogLayout>
      );
    }
    
  5. 상호 배타적인 뷰를 위한 하나의 태그된 상태. 화면이 여러 가지 중 정확히 하나를 표시할 때, 순수 함수 또는 Hook은 각 상태의 데이터를 전달하는 판별 유니온을 반환하고, 화면은 철저한 switch문입니다. 중첩 삼항 연산자나 early return 체인이 없습니다.
    // 이렇게 하지 마세요: 조건의 체인, 순서가 곧 로직이며 사례를 놓치기 쉽습니다.
    if (!loaded) return <Spinner />;
    if ("error" in loaded) return <Notice title="주문을 불러올 수 없습니다" />;
    if (order.cancelled) return <Notice title="취소됨" />;
    return order.items.length === 0 ? <EmptyBasket /> : order.paid ? <Receipt /> : <Checkout />;
    
    // 이렇게 하세요: 하나의 함수가 결정하고 각 경우에 필요한 데이터를 반환합니다.
    type OrderView =
      | { kind: "loading" }
      | { kind: "failed"; error: string }
      | { kind: "cancelled" }
      | { kind: "empty" }
      | { kind: "checkout"; order: Order }
      | { kind: "paid"; order: Order; receipt: Receipt };
    
    const view = useOrderView(id);
    switch (view.kind) {
      case "loading":   return <Spinner />;
      case "failed":    return <Notice title="주문을 불러올 수 없습니다" detail={view.error} />;
      case "cancelled": return <Notice title="취소됨" />;
      case "empty":     return <EmptyBasket />;
      case "checkout":  return <Checkout order={view.order} />;
      case "paid":      return <ReceiptPage order={view.order} receipt={view.receipt} />;
    }
    
    kind를 철저하게 사용하면 TypeScript는 새 케이스가 추가되어도 그려지지 않을 때 빌드에 실패합니다.
  6. 비즈니스 로직은 React 외부에 있습니다. 결정, 확인, 필터링, 정렬 또는 계산하는 모든 것은 React를 가져오지 않는 일반 모듈의 순수 함수이므로 렌더링 없이 재사용 및 단위 테스트가 가능합니다. Hook이나 컴포넌트가 이를 호출합니다; 포함하지 않습니다. 해당 코드가 어디로 가는지, 계층화하는 방법 및 컴포넌트에서 가져오는 방법은 business-logic 스킬에 있습니다.
    // productSearch.ts: React 가져오기가 없으므로 자체적으로 실행 및 테스트됩니다.
    export function productsMatching(products: readonly Product[], query: string) {
      const words = query.toLowerCase().split(/\s+/).filter(Boolean);
      return products.filter((p) => words.every((w) => p.name.toLowerCase().includes(w)));
    }
    
    // Hook은 그것만 호출합니다.
    const shown = productsMatching(products, query);
    
  7. 자식은 보고하고, 부모는 결정합니다. Props는 사실이 있는 이벤트(onAdd(product))여야 하며, 절대 부모의 setter가 아니어야 합니다.
    // 이렇게 하지 마세요: 자식은 부모의 setter를 전달받고 추가가 무엇을 의미하는지 결정합니다.
    <ProductCard product={p} setBasket={setBasket} setError={setError} />
    
    // 이렇게 하세요: 자식은 발생한 일을 사실과 함께 보고합니다. 부모가 결정합니다.
    <ProductCard product={p} onAdd={() => { add(p); }} />
    
  8. 두 번째로 작성될 때 반복되는 마크업은 컴포넌트가 됩니다.
    // 이렇게 하지 마세요: 네 개의 화면에 동일한 페이지 배경과 패딩이 작성되었습니다.
    <div className="relative flex h-screen w-screen flex-col bg-gray-50 p-8">...</div>
    
    // 이렇게 하세요: 두 번째로 필요할 때 한 번 작성되었습니다.
    <PageLayout>...</PageLayout>
    
  9. Hook은 얇고 파생하며, 저장하지 않습니다. Hook은 계산할 수 없는 상태만 유지합니다: 사용자가 한 일과 외부에서 도착한 것. 다른 모든 것은 렌더링 중에 해당 상태에서 규칙 6의 순수 함수에 의해 파생됩니다. prop이나 다른 state를 미러링하는 state가 없으며, 다른 state에서만 state를 설정하는 effect도 없습니다. effect는 React 외부(가져오기(fetch), 타이머, 구독, DOM)와 동기화하기 위한 것이며, 스스로 정리(clean-up)합니다. 하나의 Hook은 하나의 것을 모델링합니다.
    // 사용자가 한 일과 외부에서 도착한 것만 저장합니다.
    const [query, setQuery] = useState("");
    const { products } = useProducts();                 // 가져옴; effect가 정리됨
    
    // 나머지는 일반 모듈의 순수 함수를 사용하여 매 렌더링마다 파생합니다.
    const shown = productsMatching(products, query);
    const empty = shown.length === 0;
    
    // 이렇게 하지 마세요: 두 번 렌더링하는 effect에 의해 설정되어 표류하는 복사본.
    // const [shown, setShown] = useState(products);
    // useEffect(() => { setShown(productsMatching(products, query)); }, [products, query]);
    
  10. 분할은 그려지는 내용을 변경해서는 안 됩니다. 변경 전후의 렌더링된 마크업을 기록하고 비교하세요. 통과하는 테스트 스위트는 이동된 래퍼를 보여주지 않습니다.
# 변경 전 각 화면의 렌더링된 마크업을 기록하고, 변경한 후 다시 기록한 다음 비교합니다.
node record-markup.mjs before/   # 자체 Playwright 스크립트: 각 화면 상태를 열고 document.body를 HTML로 저장합니다.
node record-markup.mjs after/
diff -r before/ after/           # 의도한 요소만 달라야 합니다.

비교하기 전에 실행마다 변경되는 것(id, 시간, 생성된 코드)을 제거하여 실제 차이가 드러나도록 합니다.

자체 목적을 위해 분할하지 마세요: 화면은 여전히 전체적으로 읽을 수 있어야 하며, 규칙이 없는 컴포넌트에는 Hook이 필요하지 않습니다.

관련 스킬