사용자 정의 컴포넌트

우리는 커스텀 컴포넌트를 두 가지 유형으로 구분하며, 각각 다른 절차와 기대사항이 있습니다.

컴포넌트 유형

A) 프로젝트별 커스텀 컴포넌트

특정 프로젝트나 화면을 위해 만들어진 컴포넌트로, 다른 프로젝트에서 재사용할 목적으로는 만들지 않습니다.

예시:

• A Box 한 프로젝트 내에서만 사용되는 특수 레이아웃을 가진

• A Card 한 프로젝트의 화면을 위한 맞춤형 레이아웃 변형

• 프로젝트별 데이터 시각화

• 일회성 레이아웃 컴포넌트

사용 시기:

• 컴포넌트가 특정 프로젝트에만 있는 문제를 해결함

• 다른 프로젝트에서 필요할 가능성이 낮음

• 일반화하기에는 너무 구체적임

B) UI2 후보 컴포넌트

여러 프로젝트와 제품에서 재사용하도록 설계된 컴포넌트입니다.

예시:

• Navbar - 사이트 전체 내비게이션

• UserMenu - 사용자 계정 메뉴

• 표준화됨 Modal 대화상자

• UI1에서 이전 중인 컴포넌트

사용 시기:

• 컴포넌트가 여러 프로젝트에서 사용됨

• 일반적인 Decentraland 패턴을 나타냄

• UI1 컴포넌트를 대체하거나 확장함

---

프로젝트별 컴포넌트

요구사항

MUI를 기반으로 사용

반드시 가능한 한 기존 MUI 컴포넌트를 확장하세요:

// ✅ 좋음: MUI Card를 확장
import { Card as MuiCard } from '@mui/material';
import { styled } from '@mui/material/styles';

const ProjectCard = styled(MuiCard)(({ theme }) => ({
  padding: theme.spacing(3),
  display: 'flex',
  flexDirection: 'column',
  gap: theme.spacing(2),
}));

// ❌ 나쁨: 처음부터 만듦
const ProjectCard = styled('div')(({ theme }) => ({
  padding: theme.spacing(3),
  borderRadius: '4px',
  boxShadow: '0 2px 4px rgba(0,0,0,0.1)',
  // Card 기능을 중복 구현
}));

MUI가 이미 제공하는 패턴을 포크하거나 중복 구현하지 마세요:

• 사용 Card 그림자가 있는 커스텀 박스를 만드는 대신

• 사용 Button 스타일이 적용된 앵커를 만드는 대신

• 사용 TextField 커스텀 입력을 만드는 대신

• 확장 Dialog 커스텀 모달을 만드는 대신

테마 값만 사용

반드시 UI2 테마의 값만 사용하세요:

// ✅ 좋음: 모든 값이 테마에서 가져옴
const StyledBox = styled('div')(({ theme }) => ({
  color: theme.palette.text.primary,
  backgroundColor: theme.palette.background.paper,
  padding: theme.spacing(2),
  borderRadius: theme.shape.borderRadius,
  border: `1px solid ${theme.palette.divider}`,
}));

// ❌ 나쁨: 임의 값
const StyledBox = styled('div')({
  color: '#333333',
  backgroundColor: '#FFFFFF',
  padding: '16px',
  borderRadius: '8px',
  border: '1px solid #E0E0E0',
});

임의 값은 허용되지 않습니다:

• 색상: 사용 theme.palette 또는 dclColors

• 간격: 사용 theme.spacing(n)

• 테두리 반경: 사용 theme.shape.borderRadius

• 타이포그래피: 사용 theme.typography 변형

• 브레이크포인트: 사용 theme.breakpoints 헬퍼

상태 및 접근성

반드시 모든 상호작용 상태를 정의하고 구현하세요:

const ActionButton = styled('button')(({ theme }) => ({
  // 기본/유휴 상태
  padding: theme.spacing(1, 2),
  backgroundColor: theme.palette.primary.main,
  color: theme.palette.primary.contrastText,
  border: 'none',
  borderRadius: theme.shape.borderRadius,
  cursor: 'pointer',
  transition: theme.transitions.create(['background-color', 'transform']),
  
  // 호버 상태
  '&:hover': {
    backgroundColor: theme.palette.primary.dark,
  },
  
  // focus 상태(키보드 탐색)
  '&:focus-visible': {
    outline: `2px solid ${theme.palette.primary.main}`,
    outlineOffset: 2,
  },
  
  // 활성/눌림 상태
  '&:active': {
    transform: 'scale(0.98)',
  },
  
  // 비활성 상태
  '&:disabled': {
    backgroundColor: theme.palette.action.disabledBackground,
    color: theme.palette.action.disabled,
    cursor: 'not-allowed',
  },
}));

반드시 기본 접근성을 구현하세요:**

• 키보드 탐색 - 키보드로 포커스 및 조작 가능

• 포커스 표시 - 보이는 포커스 상태

• ARIA 레이블 - 텍스트가 보이지 않는 경우

• 시맨틱 HTML - 적절한 요소 사용

• 색상 대비 - WCAG AA 표준 충족

예시: 프로젝트별 컴포넌트

// src/components/LandCard/LandCard.tsx
import { Card, CardContent, CardActions, Typography, Button } from '@mui/material';
import { styled } from '@mui/material/styles';
import type { Parcel } from '@/types';

interface LandCardProps {
  parcel: Parcel;
  onTransfer: (id: string) => void;
  onView: (id: string) => void;
}

const StyledCard = styled(Card)(({ theme }) => ({
  display: 'flex',
  flexDirection: 'column',
  height: '100%',
  transition: theme.transitions.create('transform'),
  
  '&:hover': {
    transform: 'translateY(-4px)',
  },
}));

const CoordinatesText = styled(Typography)(({ theme }) => ({
  color: theme.palette.text.secondary,
  fontFamily: theme.typography.fontFamilyMono,
}));

export function LandCard({ parcel, onTransfer, onView }: LandCardProps) {
  return (
    <StyledCard>
      <CardContent>
        <Typography variant="h6" gutterBottom>
          {parcel.name || `Parcel ${parcel.x},${parcel.y}` }
        </Typography>
        <CoordinatesText variant="body2">
          ({parcel.x}, {parcel.y})
        </CoordinatesText>
        <Typography variant="body2" color="text.secondary">
          Owner: {parcel.owner}
        </Typography>
      </CardContent>
      <CardActions>
        <Button size="small" onClick={() => onView(parcel.id)}>
          보기
        </Button>
        <Button size="small" onClick={() => onTransfer(parcel.id)}>
          이전
        </Button>
      </CardActions>
    </StyledCard>
  );
}

---

UI2 후보 컴포넌트

프로젝트 간에 공유될 컴포넌트는 더 높은 기준과 더 철저한 문서화가 필요합니다.

요구사항

테마 일치

반드시 UI2 테마 값에만 의존하세요:

// ✅ 좋음: 테마 완전 통합
const NavbarContainer = styled('nav')(({ theme }) => ({
  backgroundColor: theme.palette.background.paper,
  borderBottom: `1px solid ${theme.palette.divider}`,
  padding: theme.spacing(0, 2),
  height: 64,
  display: 'flex',
  alignItems: 'center',
  gap: theme.spacing(2),
  
  [theme.breakpoints.down('md')]: {
    padding: theme.spacing(0, 1),
  },
}));

Storybook 범위

반드시 포괄적인 Storybook 스토리를 추가하세요:

필수 포함 항목:

1. 모든 props와 변형

   • 모든 prop 조합

   • 모든 크기 변형

   • 모든 색상 변형

2. 모든 상태

   • 유휴/기본

   • 로딩

   • 오류

   • 비활성화됨

   • 호버(의사 상태 애드온 사용)

   • 포커스(의사 상태 애드온 사용)

3. 상호작용

   • 클릭 핸들러

   • 폼 제출

   • 키보드 탐색

4. 색상 구성

   • 라이트 모드

   • 다크 모드

5. 반응형 동작

   • 주요 브레이크포인트(xs, md, lg)

   • 각 브레이크포인트에서의 동작을 문서화

예시 Storybook 파일:

// Navbar.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Navbar } from './Navbar';

const meta: Meta<typeof Navbar> = {
  title: 'Components/Navbar',
  component: Navbar,
  parameters: {
    layout: 'fullscreen',
  },
  argTypes: {
    variant: {
      control: 'select',
      options: ['default', 'compact'],
    },
    showUserMenu: {
      control: 'boolean',
    },
  },
};

export default meta;
type Story = StoryObj<typeof Navbar>;

export const Default: Story = {
  args: {
    variant: 'default',
    showUserMenu: true,
  },
};

export const Compact: Story = {
  args: {
    variant: 'compact',
    showUserMenu: true,
  },
};

export const WithoutUserMenu: Story = {
  args: {
    variant: 'default',
    showUserMenu: false,
  },
};

export const Loading: Story = {
  args: {
    variant: 'default',
    showUserMenu: true,
    isLoading: true,
  },
};

// 다양한 뷰포트 테스트
export const Mobile: Story = {
  args: {
    variant: 'compact',
    showUserMenu: true,
  },
  parameters: {
    viewport: {
      defaultViewport: 'mobile1',
    },
  },
};

export const Tablet: Story = {
  args: {
    variant: 'default',
    showUserMenu: true,
  },
  parameters: {
    viewport: {
      defaultViewport: 'tablet',
    },
  },
};

// 색상 구성 테스트
export const DarkMode: Story = {
  args: {
    variant: 'default',
    showUserMenu: true,
  },
  parameters: {
    backgrounds: {
      default: 'dark',
    },
  },
};

컴포넌트 구조

UI2 후보 컴포넌트는 다음 구조를 따라야 합니다:

src/components/Navbar/
├── Navbar.tsx           # 주요 컴포넌트
├── Navbar.styles.ts     # 스타일된 컴포넌트
├── Navbar.stories.tsx   # Storybook 스토리
├── Navbar.test.tsx      # 단위 테스트
├── types.ts             # TypeScript 타입
├── index.ts             # 공개 export
└── README.md            # 컴포넌트 문서

문서화 요구사항

반드시 컴포넌트 README에 포함:

1. 목적 - 어떤 문제를 해결하나요?

2. 사용법 - 컴포넌트 사용 방법

3. 속성 - 모든 props의 타입과 설명

4. 예시 - 일반적인 사용 사례

5. 접근성 - 키보드 지원, ARIA 레이블

6. 테마 - 사용하는 테마 값

7. 마이그레이션 참고사항 - UI1 컴포넌트를 대체하는 경우

예시 README:

# Navbar

사용자 메뉴와 반응형 동작을 갖춘 사이트 전체 내비게이션 컴포넌트.

## 사용법

\```tsx
import { Navbar } from 'decentraland-ui2';

function App() {
  return (
    <Navbar
      variant="default"
      showUserMenu={true}
      onLogoClick={() => navigate('/')}
      onLoginClick={handleLogin}
    />
  );
}
\```

## 속성

| 속성         | 타입                   | 기본값   | 설명                   |
| ------------ | ---------------------- | --------- | ----------------------------- |
| variant      | 'default' \| 'compact' | 'default' | 내비게이션 변형            |
| showUserMenu | boolean                | true      | 로그인 시 사용자 메뉴 표시 |
| onLogoClick  | () => void             | -         | 로고 클릭 핸들러            |
| onLoginClick | () => void             | -         | 로그인 버튼 클릭 핸들러    |

## 접근성

* 키보드 탐색: 메뉴 항목을 Tab으로 이동
* ARIA: 적절한 랜드마크와 레이블
* 스크린 리더: 메뉴 상태를 알려줌

## 테마

다음 테마 값을 사용합니다:

* `theme.palette.background.paper`
* `theme.palette.divider`
* `theme.spacing`
* `theme.breakpoints`

테스트 요구사항

반드시 다음에 대한 테스트 포함:

• Prop 렌더링

• 사용자 상호작용

• 접근성 기능

• 반응형 동작

• 오류 상태

// Navbar.test.tsx
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { Navbar } from './Navbar';

describe('Navbar', () => {
  it('로고를 렌더링해야 함', () => {
    render(<Navbar />);
    expect(screen.getByRole('banner')).toBeInTheDocument();
  });

  it('로고를 클릭하면 onLogoClick을 호출해야 함', async () => {
    const onLogoClick = jest.fn();
    render(<Navbar onLogoClick={onLogoClick} />);
    
    await userEvent.click(screen.getByRole('link', { name: /decentraland/i }));
    expect(onLogoClick).toHaveBeenCalled();
  });

  it('키보드로 탐색 가능해야 함', async () => {
    render(<Navbar />);
    const firstLink = screen.getAllByRole('link')[0];
    
    firstLink.focus();
    expect(firstLink).toHaveFocus();
  });
});

---

의사결정 매트릭스

어떤 유형의 컴포넌트를 만들지 결정할 때 사용하세요:

질문	프로젝트별	UI2 후보
다른 프로젝트에서도 이것을 사용할까요?	아니요	예
UI1에 대응 항목이 있나요?	해당 없음	아마도
Storybook 문서화가 필요합니까?	아니요	예
포괄적인 테스트가 필요합니까?	기본	광범위
디자인 리뷰가 필요합니까?	프로젝트 수준	UI2 수준
프로젝트별 패턴을 사용할 수 있나요?	예	아니요
모든 테마에서 작동해야 하나요?	아니요	예

---

승인 절차

프로젝트별 컴포넌트

1. 프로젝트 유지관리자의 코드 리뷰

2. 테마 준수 여부 확인

3. 프로젝트 환경에서 테스트

4. 승인되면 병합

UI2 후보 컴포넌트

1. 디자인 리뷰 및 승인

2. 기술 설계 리뷰

3. 구현

4. Storybook 스토리

5. 포괄적인 테스트

6. 접근성 검토

7. 코드 리뷰

8. UI2 저장소에 PR

9. 버전 관리 및 게시

10. 의존 프로젝트 업데이트

---

모범 사례

커스터마이징보다 조합

// ✅ 좋음: MUI 컴포넌트 조합
function FeatureCard({ title, children }) {
  return (
    <Card>
      <CardContent>
        <Typography variant="h6">{title}</Typography>
        {children}
      </CardContent>
    </Card>
  );
}

// ❌ 나쁨: Card 기능을 다시 구현
function FeatureCard({ title, children }) {
  return (
    <div className="custom-card">
      <div className="custom-card-content">
        <h3>{title}</h3>
        {children}
      </div>
    </div>
  );
}

점진적 향상

간단하게 시작하고 필요에 따라 기능을 추가하세요:

1. 핵심 기능이 포함된 기본 버전

2. 반응형 동작 추가

3. 접근성 기능 추가

4. 고급 상호작용 추가

5. 성능 최적화

문서화 우선

코드를 작성하기 전에:

1. 컴포넌트 README 작성

2. props 인터페이스 정의

3. 필요한 상태 나열

4. Storybook 스토리 계획

5. 그런 다음 구현

---

다음 단계

• 검토 스타일링 및 테마 구현 세부 사항용

• 참고 마이그레이션 가이드 UI1에서 UI2로의 마이그레이션용

• 확인 프로세스 개요 전체 워크플로우를 위해