@croquiscom/pds

PDS

PDS(파트너 디자인 시스템)은 카카오스타일 파트너센터 디자인 시스템을 위한 리액트 기반의 라이브러리입니다.

사용

프로젝트에 @croquiscom/pds와 peer dependencies를 추가해줍니다.

npm install --save @croquiscom/pds @emotion/react @emotion/styled react react-dom

import React from 'react'
import { value color, value text_styles, value HStack } from '@croquiscom/pds';
import styled from '@emotion/styled';

export default function Test() {
  return (
    <HStack spacing={10}>
      <BaseText kind='Heading_24_Bold' color={colors.gray900}>Hello</BaseText>
      <StyledText>PDS UI</StyledText>
    </HStack>
  );
}

const StyledText = styled.p`
  ${text_styles.Body_14_SemiBold};
  color: ${colors.gray600};
`;

개발

요구되는 개발 환경

Node.js v20+, Yarn v1.22+

로컬에 클론된 레포지토리로 이동하여, node_modules를 설치합니다.

yarn

스토리북을 통해 확인하기 위해선 다음 명령어를 실행합니다. (브라우저에서 http://localhost:6006/ 로 이동하세요.)

yarn storybook

구조

├── assets
│   ├── icons
│   └── images
├── src
│   ├── components
│   │   ├──[COMPONENT]
│   │   │   ├── index.ts
│   │   │   ├── [COMPONENT].tsx
│   │   │   ├── [COMPONENT].mdx
│   │   │   ├── types.ts
│   │   │   └── styles.ts
│   │   ├── icons
│   │   │   ├── generated
│   │   │   ├── Icon.stories.tsx
│   │   │   └── Icons.mdx
│   │   ├── images
│   │   │   ├── generated
│   │   │   ├── Image.stories.tsx
│   │   │   └── Images.mdx
│   ├── container
│   │   ├──[CONTAINER]
│   │   │   ├── index.ts
│   │   │   ├── [CONTAINER].tsx
│   │   │   ├── [CONTAINER].mdx
│   │   │   ├── types.ts
│   │   │   └── styles.ts
│   ├── constants
│   ├── foundation
│   ├── global_styles
│   ├── styles
│   ├── hooks
│   ├── stories
│   ├── types
│   ├── utils
│   ├── locales
│   └── index.ts
└── tools
    ├── svgr-icons-component-template.js
    ├── svgr-icons-template.js
    ├── svgr-images-component-template.js
    └── svgr-images-template.js

• [COMPONENT|CONTAINER]: 컴포넌트 디렉토리 이름은 소문자, 구분자는 -로 (eg. toggle-switch) 작성합니다. 하위에는 관련 컴포넌트 파일과 해당 컴포넌트의 스토리북(*.stories.tsx) 파일을 포함합니다.
  • styles.ts, types.ts과 같은 파일을 포함할 수 있습니다.
  • 컴포넌트는 Named Exports 합니다.
  • 각 컴포넌트 디렉토리와 src 하위의 index.ts를 통해 export 합니다.
• global_styles: 리셋 스타일을 포함한 글로벌 스타일을 포함합니다.
  • 리셋 스타일을 위한 class 네임은 prefix로 pds-를 붙여줍니다.
• foundation: color, typography와 같은 theme과 관련된 스타일, 스타일 토큰을 포함합니다.
• styles: 컴포넌트에 공용으로 사용할 스타일, 스타일 함수를 포함합니다.
• hooks: 커스텀 훅을 포함합니다.
• stories: 스토리북용 컴포넌트나 스타일, 컴포넌트 외의 스토리북 문서
• utils: 컴포넌트에 공용으로 사용할 유틸리티 함수들을 포함합니다.
• constants: 상수 정의를 포함합니다.
• types: 타입 정의를 포함합니다.
• assets: svg 등의 에셋을 포함합니다.
• locales: 기본표기등에 사용되는 언어셋을 포함합니다.
• scripts: 플러그인 제작을 위한 스크립트를 포함합니다.
• tools: svgr template 등의 라이브러리 제작을 위한 스크립트를 포함합니다.

아이콘 추가

⚠️ 기본적으로 피그마 플러그인을 통해 자동 생성합니다. 수동 추가를 할 경우 SVGR을 통해 svg파일을 리액트 컴포넌트로 제네레이트합니다. src/[icons|images]/generated 하위에서 직접 수정하지 말아주세요!

• assets/icons, assets/images에 svg를 추가합니다.
• yarn svgr을 실행합니다.
• src/[icons|images]/generated 하위에 제네레이트된 아이콘 리액트 컴포넌트와 src/[icons|images]/generated/index.ts에 해당 컴포넌트의 export가 추가된 것을 확인합니다.
• yarn storybook을 실행하여 스토리북 내에서 Icon/Icons, Image/Images 메뉴로 이동하여 목록에서 해당 아이콘이 잘 추가되었는지 확입니다.

PR

• main을 base 브랜치로 한 작업 브랜치를 생성합니다.
• 배포 및 버전관리를 changeset을 통해 관리하고 있습니다. PR 생성시 changeset README.md 문서를 참고하여 파일을 생성해주세요.
• PR 및 마스터 머지 시에 chromatic으로 자동 배포됩니다.

배포

Github Action을 통해 자동으로 배포하고 있습니다.

changeset 파일을 포함한 PR이 main에 머지되면, Github Action 워크플로우가 동작되며, 버전 배포를 위한 Version Packages PR이 생성됩니다. 해당 PR은 셀프로 Approve 후 머지하게 되면 Github Action의 워크플로우가 동작되며 패키지가 배포됩니다.

Github Action을 통한 배포가 불가능할 경우

npm 권한이 필요합니다. npm에 가입 후 권한을 요청해주세요.

• Version Packages PR이 생성되지 않았을 경우, 다음을 수행해 changelog와 package.json을 version bump를 포함한 작업 PR을 생성합니다.

yarn changeset version
git commit -m "chore: version bump"

• Version Packages PR이 생성되었을 경우 해당 PR을 머지하고 main을 최신 상태로 PULL 받아주세요.

yarn release

Figma Code Connect

PDS는 Figma의 Code Connect를 사용해서, Dev Mode에서 개발자가 사용할 수 있는 JSX를 바로 노출할 수 있습니다.

Code Connect를 사용하기 위해서는, PDS에서 figma 컴포넌트 매핑을 진행해야 합니다. 각 컴포넌트의 .figma.tsx가 매핑을 지원하고 있습니다.

Figma Personal access token 발급

로컬 환경에서 Code Connect를 사용하려면 Figma의 PAT (Personal Access Token)을 발급해야 합니다.

• https://www.figma.com/ 에서 로그인한 뒤, 좌측 상단의 계정 이름을 선택한 후 Settings를 누릅니다.
• Account 탭에서, 하단으로 스크롤을 내리면 Personal access tokens 항목이 있습니다. 여기서 Generate new token을 선택합니다.
  • 토큰 이름을 적당히 지정하고, Expiration을 No expiration으로 선택합니다.
  • File content는 Read-only, Code Connect는 Write로 지정합니다.
  • Generate token 버튼을 누릅니다.
• PDS에서 .env 파일을 새로 생성하고, 발급된 토큰 값을 아래와 같이 붙여넣습니다.

FIGMA_ACCESS_TOKEN=figd_...

Figma Code Connect 작업하기

PDS의 컴포넌트를 Figma와 연동하고자 하는 경우, 아래와 같은 과정으로 진행하면 됩니다.

• Figma에서 원하는 컴포넌트의 원본을 찾습니다.
  • 컴포넌트 원본은 아래와 같은 모양으로 생겼습니다.
    • 
  • 컴포넌트를 선택한 뒤, 우측의 "Go to main component"를 선택하면 이동할 수 있습니다.
• 컴포넌트를 왼쪽의 트리에서 우클릭한 후, "Copy link to selection"을 선택합니다.
  • 
• 터미널에서 해당 컴포넌트의 소스가 존재하는 디렉토리로 이동하고, 아래와 같이 명령을 실행합니다.

$ yarn figma connect create 'https://www.figma.com/design/...'

• 컴포넌트 이름에 맞는 Component.figma.tsx가 생성됩니다.
• 피그마가 제공한 기본 매핑을 실제 컴포넌트에 맞게 수정합니다. 매핑 가이드
• 작업을 마치면, 아래 명령을 통해 실제로 피그마로 업로드합니다.

$ yarn figma connect publish

• 피그마에서 해당 컴포넌트를 사용하는 곳에서 dev mode를 켜면, 실제로 해당 코드를 확인해볼 수 있습니다.
• GitHub Action 또한 세팅되어 있기 때문에, 직접 publish하지 않아도 자동으로 반영됩니다.

아이콘 업로드하기

Figma Code Connect의 아이콘, 이미지들은 scripts/figma-import-icons.js에 의해 자동으로 매핑되고 있습니다. yarn svgr을 실행하면 자동으로 피그마의 아이콘들과 매핑됩니다.

Component Test

$ yarn test

• 위 명령어 혹은 storybook ui를 통해 개발 환경에서 컴포넌트 테스트를 진행합니다.
• 특정 컴포넌트에서 발생한 이슈의 시나리오를 story의 play 함수에 정의합니다.
• 자동화 테스트와 UI테스트 스토리를 분리하기 위해 자동화 테스트코드는 [Components].test.stories.tsx 형태로 작성합니다.