MOAMOA FE Design System

모아모아의 컴포넌트 구조 및 스타일링에 대한 컨벤션입니다.

폴더/컴포넌트 구조 및 배치

• 무거운 컴포넌트들은 파일을 분리한다.
  • 카드, 리스트, 폼 등
• 가벼운 컴포넌트는 내부에 놓는다.
  • 분리하면 폴더가 지저분해지기 때문입니다.
• 스타일 컴포넌트는 내부에 놓는다.
  • 파일로 분리하면 S.Component 혹은 Styled.Component 이런 prefix가 필요한데, 이 부분이 가독성을 해치기 때문입니다.
• 공통 컴포넌트는 src/components/@shared에 배치한다.
  • 공통 컴포넌트에는 도메인 정보가 없어야 합니다.
• 페이지간에 중복 사용되는 컴포넌트 중
  • 도메인이 같은 컴포넌트는 src/components에 배치한다.
  • 도메인이 다른 경우에는 공통 컴포넌트로 분리할 수 있는지 점검하고, 그럴 수 없다면 중복을 허용한다.

예시

import Button from '@shared/button';
import List from '@shared/list';

// 컴포넌트의 props 타입을 맨 위에 둡니다.
export type StudyListProps = {
  children: React.ReactNode;
  variant?: 'primary' | 'secondary';
  onAddButtonClick: React.MouseEventHandler<HTMLButtonElement>;
  onRemoveButtonClick: React.MouseEventHandler<HTMLButtonElement>;
};

// Component는 화살표 함수로 표현하고, React.FC<Props>로 타입을 명시합니다.
// - props와 return type을 간결하게 강제할 수 있습니다.
const StudyList: React.FC<StudyListProps> = ({
  children,
  variant = 'primary',
  onAddButtonClick: handleAddButtonClick,
  onRemoveButtonClick: handleRemoveButtonClick,
}) => {
  return (
    <Self>
      <List>
        <List.Item>리팩토링 스터디</List.Item>
        <List.Item>프론트 스터디</List.Item>
        <List.Item>자바 스터디</List.Item>
      </List>
      <AddButton onClick={handleAddButtonClick}>추가하기</AddButton>
      <RemoveButton onClick={handleRemoveButtonClick}>삭제하기</RemoveButton>
    </Self>
  );
};

export default StudyList;

// styled component는 component 파일에 같이 둡니다. 왜냐하면,
// 1. 응집성 -> 위에서 바로 사용하는 컴포넌트를 바로 아래쪽에 둠으로써 아주 약간이지만 응집도를 높입니다.
// 2. 캡슐화 -> 현재 컴포넌트에서만 사용하는 하위 컴포넌트(Self, AddStudyButton, RemoveButton)는 외부에 노출(export)하지 않습니다.
// 3. styled 파일을 따로 분리하면, VSC에서 검색할 때 불편하고 외부에 노출됩니다.

// 스타일이 적용된 가장 바깥 컴포넌트는 Self로 명명합니다.
const Self = styled.div`
  ${({ theme }) => css`
    padding: 10px;
    max-width: 500px;
    border: 2px solid ${theme.color.black}; // color는 theme에 정의한 color를 사용합니다.
  `}
`;

// 공통 컴포넌트를 사용할 때는 스타일 속성을 가리고 도메인 정보를 입힙니다.
// Divider, Flex, PageTitle 등 레이아웃 관련 컴포넌트는 제외합니다.
type AddButtonProps = {
  children: React.ReactNode;
  onClick: React.MouseEventHandler<HTMLButtonElement>;
};
const AddButton: React.FC<AddButtonProps > = ({ children, onClick: handleClick }) => (
  <Button variant="primary" onClick={handleClick}>
    {children}
  </Button>
);

type RemoveButtonProps = AddButtonProps;
const RemoveButton: React.FC<RemoveButtonProps > = ({ children, onClick: handleClick }) => (
  <Button variant="danger" onClick={handleClick}>
    {children}
  </Button>
);

스타일링

• props에 대한 제어를 위해 가급적 styled component를 사용하지 않습니다.
  • styled와 일반 컴포넌트를 구별할 필요가 없어집니다.
• 공통 컴포넌트는 custom-css를 활용해 제한된 스타일만 넣을 수 있도록 강제합니다.

custom-css

공통 컴포넌트에 들어갈 수 있는 css 속성을 제한합니다. 자유를 제한해 스타일의 일관성을 지키기 위함입니다.

type ButtonProps = {
  children: React.ReactNode;
  type: 'submit' | 'button';
  fluid?: boolean;
  disabled?: boolean;
  onClick?: React.MouseEventHandler<HTMLButtonElement>;
  custom?: CustomCSS<'marginBottom'>;
};

const Button: React.FC<ButtonProps> = ({ children, type = 'button', disabled, onClick, custom }) => {
  <button css={resolveCustomCSS(custom)} disabled={disabled} type={type} onClick={onClick}>
    {children}
  </button>;
};

• custom-css 구현부는 custom-css.ts에서 확인할 수 있습니다.

Layout Component

Flex 컴포넌트를 레이아웃에 활용합니다.

JSX 가독성 높이기

스타일 정보 숨기기

JSX에 가능한 스타일 정보는 보여주지 않습니다. 역할 및 기능이 더 잘 드러나기 때문입니다.

예를 들어,

<Button type="button" variant="secondary" custom={{marginBottom: '10px'}} onClick={handleAddButtonClick}>
  추가하기
</Button>

// vs

<AddButton onClick={handleAddButtonClick} /> 

전자보다 후자 방식을 선호합니다. 즉, 가능한 도메인을 입히고 스타일 정보를 숨깁니다. 이 방식으로 구현하면 부모 컴포넌트에서 어떤 버튼인지 한눈에 파악하기 쉽습니다.

조건부 렌더링

조건부 렌더링은 즉시 실행 함수를 활용합니다.

함수 분리보다 응집도가 높고, 삼항 연산자보다 가독성이 좋기 때문입니다.

return (
  <Card backgroundColor={theme.colors.white} shadow custom={{ padding: '40px', gap: '8px' }}>
    <Card.Heading custom={{ fontSize: 'xl', marginBottom: '10px' }}>
      {(() => {
        if (isRegistered) return <AlreadyRegistered />;
        if (!isOpen) return <Closed />;
        if (!enrollmentEndDate) return <Open />;
        return <EnrollmentEndDate theme={theme} enrollmentEndDate={enrollmentEndDate} />;
      })()}
    </Card.Heading>
    <Card.Content custom={{ fontSize: 'lg' }}>
      ...
    </Card.Content>
  </Card>
);

custom-css에 대한 공원의 피드백

• 컴포넌트의 본질이 되는 속성은 주관적이다
• 이 디자인 시스템을 모르는 사람이 와도 잘 쓸 수 있을까? => 어떤 컴포넌트에는 fontSize가 본질적인 속성이고, 어떤 것은 custom에 넣어야 한다. 왜 이것은 본질이고, 저것은 아닌지 코드만 보고 판단하기 어렵다. 다시 말해서 납득 안 될 수도 있다.

병민의 생각

• Storybook에 설명을 넣으면 되지 않을까?
• 너무 자유를 주는 것보다는 좋을 것 같다!
• 주관이 많이 들어가는 건 맞다!

태태 생각

• '모아모아' 프로젝트를 위한 디자인시스템이므로 주관적인 건 당연하다.
• 그러나, 팀원 간에도 의견 차이가 있을 수 있으므로 커스텀할 필요 없는 '기본 속성'에 대해 다시 한 번 이야기를 나누는 게 좋을 것 같다.

참고

• Orbit
• Adobe React Spectrum
• MUI

디스커션

• discussion#366

꾸준히 더 좋은 구조를 찾기 위해 노력 중입니다.