Figma 작성 규칙

ids-use가 Figma 시안을 코드로(또는 코드를 시안으로) 변환하려면, 시안이 정해진 방식으로 만들어져 있어야 합니다. 이 문서는 변환이 잘 되도록 Figma 컴포넌트를 만드는 규칙입니다.

어떤 컴포넌트·prop¹을 쓸 수 있는지는 이 문서에 표로 정리하지 않습니다. 버전에 따라 달라져 문서가 실제와 어긋나기 쉽기 때문입니다. 항상 최신 상태인 CLI로 확인하세요.

• ids-use list : 어떤 컴포넌트가 있는지
• ids-use get <컴포넌트> : 그 컴포넌트의 prop·옵션 상세
• ids-use cheatsheet : render에 그대로 쓸 태그·prop·토큰 이름 정본

각 명령의 자세한 사용법은 주요 명령어에 있습니다.

1. 공통 규칙

ids-use는 시안과 코드를 서로 변환합니다. 어느 방향이든 시안이 DS의 발행된 컴포넌트와 토큰으로 만들어져 있어야 변환기가 알아봅니다. 아래를 어기면 그 연결이 끊겨 변환이 실패하거나 어긋납니다.

• 발행된 instance²만 사용: detach(분리)하거나 비슷한 도형으로 다시 그리면 변환 대상이 아닙니다.
• variant·property³ 이름·값 유지: 화면용 문구로 이름·값을 바꾸지 않습니다.
• 텍스트는 컴포넌트의 text 자리에 입력: 도형 위에 별도 Text 레이어를 겹치지 않습니다.
• 아이콘·그래픽은 instance swap⁴으로 교체: 직접 그리거나 붙이지 않습니다.
• 색·간격·모서리·그림자는 DS 토큰⁵으로, 배치는 Auto Layout⁶으로 지정: hex·px 값이나 좌표를 직접 넣지 않습니다.
• 반복 콘텐츠는 컴포넌트 slot⁷에 배치: 이름만 비슷한 임의 Frame을 slot처럼 쓰지 않습니다.

2. 폼(Field·Form) 만들기

폼은 특히 구조가 중요합니다. Field·Form은 라벨·입력·도움말·검증·간격을 자동으로 묶어 주는 폼 컴포넌트라, Figma에서도 이 구조를 그대로 써야 코드의 <Form>·<Field>로 변환됩니다. 임의 프레임으로 폼처럼 그리면 변환기가 폼으로 인식하지 못합니다.

• Field = 라벨·입력·도움말을 하나로 묶은 폼 한 칸.
  라벨 오른쪽의 sideContent와 그 아래의 content, 두 자리에 요소를 넣습니다. (예전엔 라벨을 입력 옆/위 중 어디 둘지 고르는 방향(orientation) 옵션이 있었지만, 지금은 라벨이 항상 위로 통일됐습니다.)
  • sideContent (라벨 오른쪽): 토글·버튼·텍스트 등을 둡니다.
  • content (라벨 아래 본문): Input·Select·Combobox 같은 입력을 둡니다.
  • 둘은 독립적이라 한쪽만, 또는 양쪽 모두 쓸 수 있습니다.
• Form = Field들을 담는 폼.
  입력이 하나면 Form > Field로 충분하고, 여러 개를 묶어 같은 간격을 줄 때만 Form > FieldGroup > Field를 씁니다.
• FieldGroup의 size = Field 사이 간격일 뿐, 안쪽 입력의 size와 같을 필요는 없습니다.
• 제출·검증이 있는 실제 폼은 Form 안에서 구성하고, Field 내부 부품(FieldBase·Control 등)을 개별 컴포넌트처럼 떼어 쓰지 않습니다.

<form onSubmit={handleSubmit}>
  <Field label="이메일" required helpText="업무용 이메일을 입력하세요.">
    <Input fullWidth type="email" />
  </Field>
</form>

여러 입력일 때만 FieldGroup을 추가합니다.

<form onSubmit={handleSubmit}>
  <FieldGroup size="md">
    <Field label="이름"><Input fullWidth /></Field>
    <Field label="과목"><Select collection={collection} /></Field>
  </FieldGroup>
</form>

3. 변환하고 확인하기

개발자 작성한 코드를 시안으로 변환(render)하고, 결과가 맞는지 확인하는 절차입니다. 먼저 ids-use launch로 Figma를 켜 둔 뒤 진행합니다.

1. ids-use render --file page.tsx --dry⁸로 파싱·계약 경고를 먼저 확인합니다.
2. 막는(blocking) 경고를 해결한 뒤 render합니다. 경고 0이 "보기 좋다"는 뜻은 아니므로 실물도 확인합니다.
3. render 후 ids-use screenshot으로 결과를 눈으로 확인합니다.
4. 지원되지 않는 컴포넌트·prop 경고가 나오면 임의로 우회하지 말고, 발행 상태와 ids-use get 결과를 확인합니다.

경고 코드별 해결

경고는 세 유형으로 나뉩니다. 앞의 두 유형은 render를 막으니 반드시 해결해야 하며, 마지막 하나는 배치 의도만 확인하면 됩니다.

1. 계약 위반

   ids-use가 요구하는 작성 형식을 코드가 지키지 않은 경우입니다. 그대로 render하면 그 자리가 비어 버리므로 반드시 고쳐야 합니다.

   경고 코드	해결
   W_FORM_ANCESTOR_MISSING	Field·FieldGroup·ExpandableField를 <form>·useAppForm 계약 안으로 이동
   W_PROP_UNKNOWN · W_TAG_UNMAPPED	ids-use get·ids-use cheatsheet에 있는 tag·property 이름으로 수정
   W_PAGINATION_DATA_MISSING	Pagination에 count·pageSize(필요 시 page)를 제공
   W_ITEM_NO_TEXT · W_SLOT_AMBIGUOUS	compound item 문구를 지원되는 children·text slot에 배치하고 모호한 임의 Frame을 제거

2. 값 유실

   코드에는 있는 값이 시안까지 전달되지 않은 경우입니다. 이것도 반드시 고쳐야 합니다.

   경고 코드	해결
   W_SIZE_LOST	본문+사이드 2단은 한쪽 flex="1"·다른 쪽 고정 width로 지정하고 실제 Figma 크기를 확인

3. 배치 확인

   도구가 배치 의도를 확신하지 못해 확인을 요청하는 경우입니다. 의도한 배치라면 고치지 않아도 됩니다.

   경고 코드	해결
   W_ROW_ACTIONS_UNALIGNED · W_ALIGN_LOST	액션을 오른쪽 끝에 정렬하려면 행에 justify="space-between"과 width·flex·stretch 중 하나를 명시
   W_FIELD_ROW_DESC_MISMATCH	같은 행의 Field는 description을 전부 지정하거나 전부 제거
   W_DIVIDER_VERTICAL_IN_COLUMN	세로로 쌓인 레이아웃의 항목 구분선은 가로 막대 <Divider type="horizontalBar" />로 지정 (기본값은 세로 막대)
   W_CANVAS_MASTER_UNSIZED	<EmptyState>처럼 폭 100%인 컴포넌트는 폭을 정하는 부모 안에 배치 (없으면 마스터 목업 캔버스 폭이 시안에 남음)
   W_OVERFLOW	Drawer·SidePanel처럼 고정 높이 영역은 콘텐츠를 줄이거나 컨테이너 구조를 변경

경고가 아니라 명령 자체가 실행되지 않으면(연결 실패 등) 문제 해결을 참고하세요.

4. 자주 묻는 질문