프로젝트 개요

홈쇼핑모아 서비스는 웹(Next.js)과 앱(React Native) 두 플랫폼을 동시에 운영합니다. 기존에는 디자이너가 Figma에서 토큰 값을 변경하면 개발자가 수동으로 코드를 수정하고 배포해야 했습니다. MDSA(Moa Design System Admin) 는 이 과정을 자동화하여 디자이너가 코드 없이 토큰을 편집하고 배포까지 할 수 있는 어드민 시스템입니다.

동시에 MDSA는 MCP 서버로도 동작합니다. Claude.ai, Cursor, Claude Code 등 외부 AI 툴이 MCP로 연결하면 디자인 시스템의 토큰 값, 컴포넌트 스펙, Figma 가이드라인을 실시간으로 조회하여 디자인 시스템이 완전히 적용된 코드를 생성할 수 있습니다.

핵심 기능

토큰 직접 편집 UI

Foundation 토큰을 테이블 형태로 관리하며, 실시간 프리뷰를 보면서 수정할 수 있습니다.

Color: HEX 컬러 피커 + Primitive/Semantic 계층 구분, 그룹 드래그앤드롭 순서 저장
Channel Color: 홈쇼핑사별 채널 컬러 (500/300 단계)
Typography: 폰트 사이즈, 두께, 행간 프리뷰
토큰 검색: 전체 토큰 실시간 필터링
변경 즉시 iframe CSS inject로 웹 프리뷰 반영

컴포넌트 편집 & 프리뷰

컴포넌트별 속성(props)을 관리하고, 실시간 프리뷰로 변경사항을 확인합니다.

ActionBanner, Appbar, Badge 등 컴포넌트 프리뷰 지원
속성 타입별 에디터 (텍스트, 컬러, PNG 아이콘 선택기 등)
Figma URL 연결로 디자인 원본 참조

멀티 플랫폼 배포 파이프라인

Style Dictionary v5를 활용해 하나의 토큰 소스에서 두 가지 포맷을 자동 생성합니다.

타겟	포맷	예시
웹 (Next.js)	CSS Custom Properties	`--color-primary: #0066CC`
앱 (React Native)	JS Object (단위 없음)	`colors.primary: '#0066CC'`

변환 결과는 @hsmoa/mds-tokens-web, @hsmoa/mds-tokens-rn 패키지로 사내 npm 레지스트리에 배포됩니다.

배포 & 롤백

GitHub PR 자동생성 (Octokit) + PR 상태 실시간 동기화
배포 전 변경사항 Diff 뷰로 확인
3초 카운트다운 배포 확인 모달
배포 롤백: merged PR의 토큰 상태를 복원하는 원클릭 롤백

MCP 서버 — 외부 AI 툴 연동

MDSA는 어드민 UI인 동시에 MCP 서버로 동작합니다. 외부 AI 툴이 디자인 시스템의 완전한 컨텍스트를 조회할 수 있습니다.

Claude.ai / Cursor / Claude Code
  "로그인 화면 만들어줘"
        │
        ▼ MCP 쿼리
  MDSA MCP Server
    → pgvector 유사도 검색
    → Figma 가이드라인 + 실제 토큰 값 반환
        │
        ▼
  AI가 디자인 시스템 완전히 적용한 응답 생성

MCP 툴 3종:

getTokens(category?, layer?) — 토큰 값 + 플랫폼별 사용법(CSS var / RN path) 조회
getComponentSpec(component) — 컴포넌트 스펙 + 속성 + 관련 토큰 + Figma 컨텍스트
searchGuidelines(query, limit?) — Figma + 문서 기반 가이드라인 유사도 검색

RAG 파이프라인

Figma 컴포넌트, 디자인 가이드 문서, DB 토큰을 Voyage AI(voyage-3-lite, 512차원)로 임베딩하여 Supabase pgvector에 저장합니다.

Figma REST API → 컴포넌트 구조 추출 → 청킹 → 벡터 임베딩
디자인 가이드 문서 임베딩
DB 토큰 수정 시 embedding 자동 업데이트

기술적 도전

Adapter Pattern으로 사내 인프라 마이그레이션 대비

검증 단계에서는 Supabase, Voyage AI 등 외부 서비스를 사용하지만, 추후 사내 인프라로 교체할 때 앱 코드를 건드리지 않아도 됩니다.

앱 코드 → /lib/*/adapter.ts → 현재: Supabase / Voyage AI
                                추후: 사내 DB / 사내 AI

모든 외부 SDK는 /lib 하위 어댑터에만 존재하며, 앱 코드는 내부 인터페이스만 import합니다.

도메인	역할	현재 어댑터
`lib/db/`	토큰/컴포넌트 CRUD	Supabase
`lib/ai/`	512차원 임베딩	Voyage AI
`lib/storage/`	벡터 저장/검색	Supabase pgvector
`lib/github/`	PR 자동생성	Octokit
`lib/figma/`	컴포넌트 구조 추출	Figma REST API
`lib/mcp/`	외부 AI 툴 인터페이스	MCP SDK

3계층 토큰 구조 설계

Primitive (원시값)  →  Semantic (의미 부여)  →  Component (컴포넌트 전용)
color.blue.500         color.primary              button.background

Primitive와 Semantic을 분리하여 시즌 테마 전환 시 Semantic 레이어만 교체하면 되도록 설계했습니다.

모노레포 구조로 패키지 독립 배포

packages/
  @hsmoa/tokens             # 토큰 정의 원본
  @hsmoa/mds-tokens-web     # CSS Custom Properties
  @hsmoa/mds-tokens-rn      # RN JS Object

각 패키지는 독립적으로 사내 npm 레지스트리(npm-registry.buzzni.com)에 배포 가능하며, workspace 프로토콜로 내부 참조합니다.

개발 현황

Phase 1 — 토큰 편집 & 배포 (완료)

Foundation 토큰 CRUD (Color, Channel Color, Typography)
직접 편집 UI + 실시간 웹 프리뷰 (iframe CSS inject)
컬러 그룹 드래그앤드롭 순서 저장, 접기/펼치기
토큰 검색
컴포넌트 편집 (속성 관리, Figma URL, PNG 아이콘 선택기)
컴포넌트 프리뷰 (ActionBanner, Appbar, Badge)
Style Dictionary 웹/RN 변환
변경사항 Diff 뷰 + GitHub PR 자동생성
배포 이력 + PR 상태 GitHub 동기화
배포 롤백 (merged PR 토큰 복원)
3초 카운트다운 배포 확인 모달
PNG 아이콘 카탈로그

Phase 2 — RAG 파이프라인 & MCP 서버 (완료)

Voyage AI 임베딩 어댑터 (voyage-3-lite, 512차원)
Supabase pgvector 기반 벡터 저장/검색
Figma → 컴포넌트 청킹 → pgvector 임베딩
디자인 가이드 문서 임베딩
DB 토큰 수정 시 embedding 자동 업데이트
MCP 서버 구현 (getTokens, getComponentSpec, searchGuidelines)
임베딩 수동 트리거 API

Phase 3 — 고도화 (진행 예정)

React Native Expo Snack 임베드 프리뷰
시즌 테마 일괄 생성 (외부 AI 툴 + MCP)
배포 권한 레벨 관리
컴포넌트 사용처 추적
Figma Webhook 실시간 동기화
Spacing / Shadow / Radius 편집

홈쇼핑모아 디자인 시스템 어드민 (MDSA)