Ficnic

Figma 플러그인 기반 디자인 토큰 관리 도구

Tokens Studio + Style Dictionary를 하나로 합친 플러그인. 디자이너가 Figma 안에서 직접 디자인 토큰을 만들고, GitHub에 푸시하고, CSS/TypeScript로 변환까지 끝낼 수 있습니다.

---

왜 만들었나

기존 워크플로에는 두 가지 문제가 있었습니다.

문제	내용
비용	Tokens Studio GitHub 연동은 유료 플랜 전용
복잡성	Tokens Studio + Style Dictionary 두 툴을 따로 관리
포맷	원하는 JSON 구조로 커스터마이징 불가
품질	잘못된 토큰 이름을 잡아주지 않음
구조	3-tier(Primitive → Semantic → Component) 강제/가이드 없음

Ficnic은 이 모든 것을 Figma 플러그인 하나로 해결합니다.

---

주요 기능

3-tier 토큰 구조

Primitive  →  Semantic      →  Component
#3B82F6       color.primary     button.background

토큰 간 참조({color.primary})로 일관성 있는 시스템 구축. 같은 그룹명의 위 티어 토큰을 클릭 한 번으로 참조 삽입.

GitHub 직접 푸시

PAT 토큰만 있으면 서버 없이 GitHub REST API로 직접 푸시. 파일이 없으면 생성, 있으면 SHA 기반 업데이트.

다양한 내보내기 포맷

포맷	예시
CSS Variables	--color-primary: #3B82F6;
TypeScript	export const tokens = { ... } as const
Style Dictionary	{ "value": "#3B82F6", "type": "color" }
W3C Design Tokens	{ "$value": "#3B82F6", "$type": "color" }
Raw JSON	원본 구조 그대로
커스텀	prefix, separator, key 이름 자유 설정

DX 분석 도구

• 순환 참조 감지 — A → B → A 무한 루프 경고
• 미사용 토큰 감지 — 어디서도 참조되지 않는 토큰 표시
• 영향 범위 시각화 — 토큰 변경 시 영향받는 토큰 수 표시
• Figma 스타일 sync — 로컬 색상 스타일과 토큰 불일치 검사

네이밍 lint

이모지, 특수문자, 연속 점 등 잘못된 이름 실시간 감지.

---

시작하기

요구사항

• Node.js 18+
• Figma Desktop App

설치 및 로컬 실행

git clone https://github.com/eveneul/Ficnic.git
cd Ficnic
npm install
npm run build

Figma에 플러그인 등록

1. Figma Desktop → 메뉴 → Plugins → Development → Import plugin from manifest
2. 프로젝트 폴더의 manifest.json 선택
3. Plugins → Development → Ficnic 실행

개발 모드 (브라우저 미리보기)

npm run dev:ui       # UI watch 빌드
npm run dev:sandbox  # sandbox watch 빌드

dist/index.html을 브라우저에서 열면 mock 데이터로 UI 미리보기 가능.

---

GitHub 연동 설정

1. GitHub → Settings → Developer settings → Personal access tokens → Generate new token
2. repo 권한 선택 후 발급
3. 플러그인 GitHub 탭에서 입력
   • PAT 토큰
   • Owner (GitHub 유저명)
   • Repository 이름
   • Branch
   • 파일 경로 (예: tokens/tokens.json)
4. 설정 저장 → GitHub에 푸시

---

Figma 스타일 sync 사용법

1. Figma에서 색상 로컬 스타일 생성 (예: color/primary → #3B82F6)
2. 플러그인 Sync 탭 → 검사 시작
3. 불일치 항목 확인 후 토큰 업데이트

Figma 스타일 이름의 /는 .으로 자동 변환되어 토큰 이름과 비교됩니다. (color/blue/500 → color.blue.500)

---

기술 스택

• Vite + React 19 + TypeScript
• Figma Plugin API (@figma/plugin-typings)
• GitHub REST API (PAT 인증, 서버리스)
• lucide-react (아이콘)
• vite-plugin-singlefile (UI를 단일 HTML로 인라인)

빌드 구조

src/
├── ui/          # 플러그인 UI (React, DOM 접근 가능)
│   ├── components/
│   ├── hooks/
│   ├── styles/
│   └── dev/     # 브라우저 개발용 mock 데이터
├── sandbox/     # Figma API 전용 (figma.* 여기서만 사용)
├── core/        # 순수 로직 (변환, lint, resolve, 분석)
└── types/       # 공유 타입 정의

dist/
├── index.html   # UI 단일 파일 (JS/CSS 전부 인라인)
└── sandbox.js   # Figma sandbox IIFE

UI ↔ sandbox는 postMessage로만 통신 (Figma 보안 정책).

---

로드맵

Phase	기능	상태
P0	토큰 편집 UI, 네이밍 lint, GitHub 푸시	✅
P1	CSS/TS 변환, 포맷 템플릿 3종, 커스텀 포맷	✅
DX	순환 참조, 미사용 토큰, 영향 범위, Figma sync	✅
P2	실시간 미리보기	예정

---

라이선스

MIT