당근 디자인 시스템 SEED, llms.txt와 MCP로 AI 에이전트에게 문서를 여는 방법

9bow · 8월 1, 2026, 6:30오전

당근 디자인 시스템 SEED 소개

SEED는 당근이 제품을 만들 때 쓰는 디자인 시스템으로, 색과 타이포그래피, 간격 같은 시각 요소부터 버튼과 리스트 같은 컴포넌트, 눌렀을 때의 반응 같은 모션까지를 하나의 체계로 정리한 결과물입니다. Apache License 2.0으로 GitHub에 공개되어 있고, 2026년 7월 현재 960개의 별을 받았습니다. 국내 기업이 공개한 디자인 시스템 중에서는 문서와 코드, 디자인 스펙이 함께 유지되는 드문 사례입니다.

디자인 시스템 자체는 AI 이야기가 아닙니다. 그런데 SEED가 최근 붙인 AI & Tools 섹션은 AI/ML 쪽에서 보아도 흥미로운 구조를 갖고 있습니다. SEED 팀은 자기 문서를 사람만 읽는 참고 자료로 두지 않고, LLM이 그대로 읽을 수 있는 llms.txt, 에이전트가 도구로 호출하는 MCP(Model Context Protocol) 서버 두 종, 그리고 코딩 에이전트가 판단 절차까지 위임받는 Agent Skill을 한꺼번에 제공합니다. 문서 사이트 하나를 놓고 텍스트 레이어, 도구 레이어, 워크플로 레이어 를 층층이 쌓아 올린 셈입니다.

이 구조가 눈에 띄는 이유는 지금 코딩 에이전트가 UI 코드를 짤 때 가장 자주 실패하는 지점을 정면으로 겨냥하기 때문입니다. 에이전트는 React를 잘 쓰지만 우리 팀의 디자인 시스템은 모릅니다. 그래서 존재하지 않는 컴포넌트를 import하고, 팔레트에 없는 색을 하드코딩하고, 이미 폐기된 API를 되살려 놓습니다. SEED가 택한 답은 에이전트를 더 똑똑하게 만드는 쪽이 아니라, 시스템의 기준 자체를 기계가 읽을 수 있는 형태로 내보내는 쪽이었습니다.

이 글에서는 SEED의 AI 통합 네 개 층을 하나씩 살펴보고, 그 층들이 올라앉은 SEED V3 개편과 브랜딩 작업까지 함께 정리합니다. 자기 팀의 문서나 라이브러리를 에이전트에 열어 주려는 분들에게는 그대로 따라 볼 만한 참고 사례가 될 것입니다.

디자인 시스템은 왜 AI 에이전트의 문제가 되었을까

지난 1년 사이 커뮤니티에서 부쩍 늘어난 주제가 "에이전트에게 디자인 컨텍스트를 어떻게 넘기는가" 입니다. Atlassian이 공개한 DESIGN.md처럼 디자인 규칙을 마크다운 한 장으로 압축해 넘기는 접근이 있고, DESIGN.md 모음집처럼 그 포맷을 표준화하려는 시도도 있습니다. designlang처럼 이미 배포된 웹사이트에서 디자인 시스템을 역으로 추출하는 도구, Google Stitch처럼 프롬프트에서 UI를 바로 생성하는 서비스도 나왔습니다.

이 시도들이 공통으로 부딪히는 벽은 압축률과 정확도의 교환 입니다. 마크다운 한 장에 담을 수 있는 정보량은 정해져 있는데, 실제 디자인 시스템은 컴포넌트 수십 개와 토큰 수백 개, 각 컴포넌트의 상태와 접근성 스펙까지 안고 있습니다. 한 장으로 줄이면 세부가 날아가고, 전부 넣으면 컨텍스트 윈도우가 터집니다.

SEED의 접근은 압축을 포기하고 탐색 을 택합니다. 문서 전체를 한 번에 밀어 넣는 대신, 에이전트가 필요한 문서만 골라 가져가도록 계층적인 인덱스와 도구를 제공합니다. 이 발상은 MCP 프로토콜이 겨냥한 문제와 정확히 같고, 그래서 SEED의 구현도 자연스럽게 MCP 서버로 귀결됩니다.

SEED가 AI 에이전트에게 문서를 여는 네 개의 층

SEED의 AI 통합을 한 표로 정리하면 다음과 같습니다. 아래로 갈수록 원시적이고 범용적이며, 위로 갈수록 SEED에 특화되고 자동화 수준이 높습니다.

층	구성요소	하는 일	필요한 도구
워크플로	`seed-design` Agent Skill	프로젝트 상태를 읽고 어떤 문서를 볼지 스스로 분기	Claude Code 등 스킬 지원 에이전트
디자인 변환	`@seed-design/mcp` (Figma MCP)	Figma 레이어를 SEED React 코드로 변환	Figma PAT 또는 Figma 플러그인
도구	`@seed-design/docs-mcp` (Docs MCP)	컴포넌트, 토큰, 아이콘 문서를 도구 호출로 조회	MCP 클라이언트
문서	`llms.txt`, `llms-full.txt`	문서 전체를 LLM이 읽을 수 있는 평문으로 노출	없음, HTTP GET만

네 층은 서로를 대체하지 않고 겹쳐 쓰입니다. llms.txt는 도구 설치 없이 URL만으로 동작하는 최저 진입장벽 경로이고, Docs MCP는 같은 문서를 도구 호출로 감싸 에이전트가 능동적으로 검색하게 만듭니다. Figma MCP는 문서가 아니라 디자인 파일을 소스로 삼고, Agent Skill은 그 아래 세 층을 언제 어떻게 쓸지 정하는 판단 규칙을 담습니다.

첫 번째 층, llms.txt로 문서 전체를 기계가 읽게 만들기

llms.txt는 사이트 루트에 마크다운 인덱스 파일을 두어 LLM이 사람용 HTML을 파싱하지 않고도 콘텐츠 구조를 파악하게 하자는 제안입니다. SEED는 이 규약을 단순히 따르는 데서 멈추지 않고, 섹션마다 별도의 진입점을 두는 계층 구조로 확장했습니다.

루트 llms.txt는 11개 섹션의 표 하나로 되어 있습니다. Get Started, Foundations, Components, Patterns, Design Guidelines, React Library, Breeze Utilities, Lynx, AI Integration, Updates, Changelog가 각각 자기 llms.txt 주소를 갖습니다. 에이전트는 루트를 한 번 읽어 어디를 파고들지 정하고, 해당 섹션의 인덱스로 내려갑니다.

인덱스와 전문을 나눈 두 갈래 주소

여기서 SEED가 둔 설계 결정 하나가 실용적입니다. 섹션마다 llms.txt와 llms-full.txt 를 구분해 두었습니다.

llms.txt (인덱스): 그 섹션에 어떤 문서가 있는지 제목과 한 줄 설명, 개별 문서 주소만 나열합니다. 크기가 작아 컨텍스트를 거의 쓰지 않습니다. 예를 들어 Foundations 인덱스는 색상, 타이포그래피, 아이콘, 레이아웃, 모션 등 20개 문서를 4KB 안에 정리합니다.
llms-full.txt (전문): 그 섹션의 모든 문서를 한 파일로 이어 붙입니다. Design Guidelines, React Library, Breeze Utilities, Lynx, AI Integration 다섯 섹션이 제공하며, 예컨대 AI Integration 전문은 약 59KB로 MCP 서버 두 종과 Agent Skill의 전체 내용을 담고 있습니다.

이 이원화가 왜 중요한지는 실제로 써 보면 드러납니다. "SEED에 어떤 컴포넌트가 있나" 를 물을 때는 인덱스만 읽으면 충분한데, 전문을 받으면 수만 토큰을 낭비합니다. 반대로 "MCP 설정을 처음부터 끝까지 알려줘" 같은 요청은 문서 사이를 오가야 하므로 전문을 한 번에 받는 편이 왕복을 줄입니다. 판단을 에이전트에 맡기되 두 선택지를 모두 준 것입니다.

개별 문서까지 내려가는 규칙적인 주소 체계

인덱스 아래 개별 문서는 예측 가능한 규칙을 따릅니다.

https://seed-design.io/llms/react/components/{component-name}.txt
https://seed-design.io/llms/foundations/color.txt
https://seed-design.io/llms/updates/how-seed-evolved.txt

예를 들어 Action Button의 React API 문서는 /llms/react/components/action-button.txt에 있습니다. 주소가 규칙적이라 에이전트는 컴포넌트 이름만 알면 검색 없이 문서를 곧장 가져올 수 있습니다. 문서 사이트가 아무리 커져도 이 규칙 하나로 커버되는 것이 이 방식의 강점입니다.

현재 인덱스에 올라 있는 문서 규모를 세어 보면 React 컴포넌트 문서 76개(이 중 13개는 deprecated 표시), 디자인 스펙 기준 컴포넌트 56개, Foundations 문서 20개, Lynx 문서 27개입니다. 이 정도 분량이면 한 번에 밀어 넣는 방식은 애초에 성립하지 않습니다.

llms.txt 더 알아보기

llms.txt 제안 원문 - Jeremy Howard가 제시한 규약 명세

SEED 루트 llms.txt - 11개 섹션 진입점 인덱스

https://seed-design.io/llms.txt

두 번째 층, Docs MCP로 문서를 도구로 바꾸기

@seed-design/docs-mcp는 SEED 문서를 위한 공식 MCP 서버입니다. 같은 문서를 다루지만 llms.txt와 결정적으로 다른 점이 있습니다. llms.txt는 에이전트가 주소를 알아야 읽을 수 있는 수동적 자료인데, MCP 서버는 에이전트에게 도구 목록을 먼저 알려 주고 필요할 때 호출받는 능동적 인터페이스입니다. 에이전트가 SEED 문서의 존재를 몰라도, 도구 설명을 보고 스스로 "여기 물어보면 되겠다" 고 판단합니다.

설치는 한 줄

Figma 연결이 필요 없어 설치가 간단합니다. Claude Code와 Codex CLI는 명령 한 줄로 끝납니다.

claude mcp add seed-docs -- npx -y @seed-design/docs-mcp

codex mcp add seed-docs -- npx -y @seed-design/docs-mcp

Gemini CLI나 Cursor, Claude Desktop처럼 설정 파일을 쓰는 도구는 아래 형태를 각자의 설정에 넣습니다. Cursor는 type 필드를 추가로 요구합니다.

{
  "mcpServers": {
    "seed-docs": {
      "command": "npx",
      "args": ["-y", "@seed-design/docs-mcp"],
      "type": "stdio"
    }
  }
}

여섯 개 범주로 나뉜 도구 카탈로그

Docs MCP가 제공하는 도구는 discovery, react, breeze, design-guidelines, rootage, icons 여섯 범주로 나뉩니다. category 파라미터에 이 값을 넣어 필요한 범주만 걸러낼 수 있습니다. 범주별 대표 도구를 정리하면 다음과 같습니다(react 범주는 컴포넌트용 도구와 문서 섹션용 도구로 다시 갈립니다).

범주	대표 도구	반환하는 것
Discovery	`discover_tools`	사용 가능한 도구 목록과 각 도구의 용도
React Components	`list_react_components`, `get_react_component`	컴포넌트 목록, 설치 방법과 props와 사용 예시
React 섹션별	`list_react_getting_started`, `get_react_migration` 등	설치, Stackflow 통합, Codemod, 마이그레이션 문서
Breeze	`list_breeze_components`, `get_breeze_component`	유틸리티 UI 컴포넌트 문서
Design Guidelines	`list_docs_components`, `get_docs_component`	컴포넌트 해부도(anatomy)와 속성, 사용 권장사항
Rootage	`get_rootage`	디자인 토큰과 컴포넌트 스펙의 원본 JSON
Icons	`list_icons`, `search_icons`, `get_icon_details`	아이콘 목록, 키워드 검색, React import 문

React 섹션은 특히 촘촘합니다. Getting Started, Stackflow, Developer Tools, Migration, AI Integration, Updates 여섯 섹션마다 list_*와 get_* 짝이 붙습니다. 에이전트는 먼저 목록을 받아 경로를 확인하고, 그 경로로 상세 문서를 가져오는 2단 호출을 합니다.

list_react_getting_started()
→ Installation - Vite (path: installation/vite)
  CLI - Commands (path: cli/commands)
  Styling - Theming (path: styling/theming)
  ...

get_react_getting_started({ path: "installation/vite" })

도구를 찾아 주는 도구, discover_tools

도구가 스무 개를 넘어가면 에이전트 쪽에서도 무엇을 불러야 할지 헷갈립니다. SEED는 discover_tools라는 메타 도구를 두어 이 문제를 다룹니다. query로 검색어를, category로 범주를 걸러 필요한 도구만 추려 볼 수 있습니다.

discover_tools({ query: "component" })

MCP 서버에 처음 연결한 직후 이 도구를 한 번 호출하면 전체 지형을 파악할 수 있습니다. 도구 정의를 모두 시스템 프롬프트에 올려 두는 대신 필요할 때 탐색하게 만드는 방식이라, 컨텍스트 절약 측면에서도 이득이 있습니다.

아이콘 검색이 한국어를 받는다

작지만 실용적인 배려가 아이콘 검색입니다. search_icons는 영어와 한국어 검색어를 모두 받습니다.

search_icons({ query: "화살표" })

Found 15 icons matching "화살표":
View in browser: https://seed-design.io/foundations/iconography/library?search=화살표

- icon_arrow_left_line [monochrome] (line)
  Matched: arrow, 화살표, left
- icon_arrow_right_line [monochrome] (line)
  Matched: arrow, 화살표, right
...

get_icon_details를 부르면 아이콘의 타입과 변형, 키워드에 더해 React import 문까지 그대로 돌려줍니다. 에이전트가 아이콘 이름을 추측해 존재하지 않는 컴포넌트를 import하는 실패를 막아 주는 장치입니다.

import { IconArrowLeftLine } from "@karrotmarket/react-monochrome-icon"

<IconArrowLeftLine />

아이콘은 모노크롬(line, fill)과 멀티컬러로 나뉘고, 멀티컬러는 중고거래나 부동산처럼 서비스 카테고리로 필터링됩니다. SEED V3 개편 때 일관된 형태와 네이밍 규칙으로 약 300개를 새로 정리한 결과물입니다.

커스텀 서버에 끼워 넣기

@seed-design/docs-mcp는 npm 패키지로도 설치되어, 사내 MCP 서버에 SEED 도구만 합쳐 넣는 것도 가능합니다. transport는 호출하는 쪽이 정합니다.

import { server } from "@seed-design/docs-mcp/server";
import { initializeTools } from "@seed-design/docs-mcp/tools";

// 도구 초기화
await initializeTools(server);

// 원하는 transport와 함께 사용
// 예: stdio, HTTP, SSE 등

로컬에서 동작을 확인할 때는 MCP Inspector를 붙여 브라우저에서 도구를 하나씩 눌러 볼 수 있습니다.

npx @modelcontextprotocol/inspector bun ./dist/stdio.js

Docs MCP 더 알아보기

SEED Docs MCP 공식 문서 - 도구 목록과 파라미터 전체 명세

docs-mcp 패키지 소스 - daangn/seed-design 저장소의 packages/docs-mcp

MCP Inspector - 브라우저에서 MCP 도구를 테스트하는 공식 도구

세 번째 층, Figma MCP로 디자인을 React 코드로 옮기기

@seed-design/mcp는 Figma 디자인을 SEED React 코드로 변환하는 MCP 서버입니다. 여기서 다루는 소스는 문서가 아니라 디자인 파일이므로, Figma에 접근할 방법이 필요합니다. SEED는 두 가지 경로를 모두 지원합니다.

REST API와 WebSocket, 두 가지 접근 경로

방식	인증	동작	제약
REST API	Figma Personal Access Token 필요	Figma URL을 복사해 에이전트에 전달	실시간 선택 기반 도구 사용 불가
WebSocket	토큰 불필요	Figma 플러그인이 선택한 레이어를 실시간 전달	Bun 런타임과 플러그인 설치 필요

REST API 방식은 토큰에 file_content:read, file_metadata:read, file_variables:read, library_assets:read, library_content:read, team_library_content:read, file_dev_resources:read 일곱 가지 읽기 권한을 부여해야 합니다. 설치 후 사용법은 Figma에서 레이어 주소를 복사해(⌘ + L) 그대로 넘기는 식입니다.

https://www.figma.com/design/abc123/MyDesign?node-id=123-456 이 레이어의 React 코드를 가져와주세요.

WebSocket 방식은 토큰 발급 없이 시작할 수 있는 대신 백그라운드 서버를 띄우고 Figma MCP 플러그인을 설치해야 합니다. 서버 실행에는 Bun이 필요하며 --bun 플래그를 붙입니다.

bunx --bun @seed-design/mcp@latest socket

이 경로에서는 레이어를 직접 선택한 뒤 이렇게 말하면 됩니다.

지금 선택한 레이어의 React 코드를 가져와주세요.

--mode로 등록되는 도구 범위를 줄이기

도구가 많아지면 시스템 프롬프트가 무거워집니다. SEED는 --mode 옵션으로 등록 도구를 제한해 컨텍스트를 줄일 수 있게 했습니다. 옵션을 주지 않으면 all 이 기본값입니다.

모드	등록 도구	비고
`all` (기본값)	모든 도구	PAT가 있으면 REST 우선, WS 전용 도구는 WebSocket 사용
`rest`	REST API 도구만	`get_selection` 등 WebSocket 전용 도구 미등록
`websocket`	WebSocket 도구만	현재 모든 도구가 WebSocket으로 동작 가능, PAT 무시

이 설계가 깔끔한 이유는 같은 도구를 두 전송 방식이 공유하도록 짰기 때문입니다. Figma URL이나 fileKey + nodeId를 주면 REST로, nodeId만 주면 WebSocket으로 동작합니다. 호출하는 쪽이 전송 방식을 신경 쓰지 않아도 되는 셈입니다.

공통 도구와 WebSocket 전용 도구

모든 모드에서 등록되는 공통 도구는 여섯 개입니다.

도구	설명
`get_node_info`	레이어의 구조 정보를 반환
`get_nodes_info`	여러 레이어의 구조 정보를 한 번에 반환
`get_node_react_code`	레이어의 React 코드를 생성
`get_component_info`	컴포넌트의 key와 속성 정의를 반환
`find_nodes`	하위 레이어를 이름(정규식)으로 검색해 ID 목록 반환
`retrieve_color_variable_names`	SEED 색상 변수 이름 목록을 반환

Figma 플러그인과의 통신이 필요한 WebSocket 전용 도구도 여섯 개가 있습니다. get_selection으로 현재 선택한 레이어 ID를 받고, get_document_info로 문서 정보를, export_node_as_image로 레이어를 PNG나 JPG, SVG, PDF로 내보냅니다. 여기에 Figma Annotation을 읽고 쓰는 get_annotations와 add_annotations, 채널 참가용 join_channel이 더해집니다.

이 목록에서 add_annotations 는 방향이 다릅니다. 나머지 도구가 디자인을 읽어 오는 쪽이라면, 이 도구는 Figma 파일에 측정값과 주석을 되돌려 씁니다. 에이전트가 생성한 코드의 근거를 디자인 파일 쪽에 남길 수 있으니, 읽기만 하던 흐름이 양방향으로 열립니다.

ComponentHandler로 사내 디자인 시스템까지 확장하기

get_node_react_code는 기본적으로 SEED Figma 컴포넌트만 인식합니다. 팀 내부 디자인 시스템을 쓰는 경우에는 ComponentHandler 를 직접 작성해 Figma 컴포넌트를 원하는 React 컴포넌트로 매핑할 수 있습니다. 설정 파일은 .js, .mjs, .ts, .mts 를 지원하며 --config 플래그로 로드합니다.

bunx --bun @seed-design/mcp@latest --config /path/to/config.ts

설정 파일은 Figma 컴포넌트 key와 변환 함수를 짝지어 등록하는 형태입니다.

import {
  type react,
  defineComponentHandler,
  createElement,
} from "@seed-design/figma";

export default {
  extend: {
    componentHandlers: [
      (_deps: react.ComponentHandlerDeps) =>
        defineComponentHandler(
          "figma_component_key",
          ({ componentProperties: props }) => {
            const tone = props.Tone.value.toLowerCase();

            return createElement("CustomButton", {
              tone,
            });
          },
        ),
    ],
  },
} satisfies react.CreatePipelineConfig;

재미있는 대목은 SEED가 이 ComponentHandler를 에이전트에게 작성시키는 프롬프트를 문서에 함께 넣어 두었다 는 점입니다. 문서에는 get_selection()으로 선택 노드를 확인하고, get_component_info(nodeId)로 컴포넌트 key와 variant 정의를 수집한 뒤, 정해진 패턴으로 핸들러를 구현하라는 구현 가이드가 마크다운 그대로 제공됩니다. 이 프롬프트를 파일로 저장한 다음 대상 컴포넌트와 함께 넘기면 됩니다.

@CustomButton.tsx @ComponentHandlerRule.md CustomButton 컴포넌트의 ComponentHandler를 구현해주세요.

Figma MCP를 써서 Figma MCP의 확장 코드를 쓰게 하는 구조인데, 실제 SEED Slider 컴포넌트를 SEED React <Slider />로 매핑하는 ComponentHandler 예시가 저장소에 함께 공개되어 있습니다.

Figma MCP 더 알아보기

SEED Figma MCP 공식 문서 - 설치, 모드, 도구 목록, 커스텀 설정

Figma Code Connect - Figma 컴포넌트와 실제 코드를 연결하는 공식 기능

네 번째 층, Agent Skill로 판단 절차까지 넘기기

가장 위층은 seed-design Agent Skill입니다. MCP가 "무엇을 조회할 수 있는가" 를 제공한다면, 스킬은 "어떤 상황에서 무엇을 조회하고 어떻게 판단할 것인가" 를 제공합니다. Anthropic이 Claude에 도입한 Agent Skills 형식을 그대로 따르며, 설치는 skills add 명령 한 줄입니다.

npx skills add https://github.com/daangn/seed-design --skill seed-design

스킬은 SKILL.md 한 장과 참조 문서 여섯 개로 구성됩니다.

seed-design/
├── SKILL.md
└── references/
    ├── getting-started.md
    ├── components.md
    ├── foundation.md
    ├── usage.md
    ├── migration.md
    └── upgrade.md

프로젝트 상태를 먼저 읽고 분기한다

SKILL.md가 정의한 동작 순서에서 첫 단계는 사용자 질문에 답하는 것이 아니라 프로젝트를 읽는 것 입니다. seed-design.json 존재 여부로 초기 설정이 끝났는지 확인하고, package.json에서 @seed-design/react와 @seed-design/css 버전을 확인하고, vite.config나 rsbuild.config 같은 파일로 번들러를 감지합니다. 락 파일로 패키지 매니저까지 판별합니다.

bun.lockb 또는 bun.lock → Bun
pnpm-lock.yaml → pnpm
yarn.lock → Yarn
package-lock.json 또는 기본값 → npm

이후 안내하는 모든 설치 명령이 감지된 패키지 매니저에 맞춰 나옵니다. 사소해 보이지만, 에이전트가 npm install을 제안했다가 락 파일이 깨지는 흔한 사고를 원천에서 막는 규칙입니다.

상태 파악이 끝나면 질문 유형에 따라 참조 문서로 분기합니다. seed-design.json이 없으면 getting-started.md, 컴포넌트 질문이면 components.md, 색상과 타이포와 테마 질문이면 foundation.md, CLI 사용법이면 usage.md, 버전 호환이면 migration.md, 업그레이드 진단이면 upgrade.md 입니다. 필요한 참조 문서만 읽어 들이므로 컨텍스트 사용이 질문 범위에 비례합니다.

CLI는 데이터를, 스킬은 해석을

가장 참고할 만한 설계는 업그레이드 진단 워크플로입니다. upgrade.md는 역할 분담을 이렇게 못 박습니다. "CLI는 데이터 fetch만 담당하고, 이 스킬이 해석과 분석을 담당합니다."

구체적으로 @seed-design/cli의 docs --raw 명령이 changelog 원문을 가져오고, 그 마크다운을 해석해 프로젝트 영향도를 판단하는 일은 스킬이 맡습니다.

# 전체 changelog (모든 패키지)
npx @seed-design/cli@latest docs react/updates/changelog --raw

# 특정 패키지의 버전 인덱스
npx @seed-design/cli@latest docs react/updates/changelog/react --raw

# 특정 버전 이후 changelog
npx @seed-design/cli@latest docs react/updates/changelog/react/1.2.5 --raw

changelog를 받은 뒤 스킬은 Breaking Changes에 언급된 컴포넌트 이름과 prop 이름, API 시그니처를 프로젝트 코드에서 검색해 실제 영향 범위를 추립니다. 보고 형식도 정해져 있어서, 수정 필요, 확인 권장, 영향 없음 세 갈래로 정리해 돌려줍니다. 프로젝트 환경이 없으면 영향도 분석을 건너뛰고 changelog 요약만 제공합니다.

호환성 검사는 아예 CI 게이트로 쓸 수 있게 만들어 두었습니다. compat 명령은 설치된 패키지 버전과 프로젝트에 복사된 스니펫의 요구 버전이 어긋나면 종료 코드 1 로 끝납니다.

npx @seed-design/cli@latest compat --all

추측하지 말고 질문하라

스킬 문서에서 눈에 띄는 또 하나는 에이전트에게 모르면 묻도록 명시한 부분입니다. upgrade.md는 패키지나 버전을 특정할 수 없을 때의 행동을 판단 트리로 그려 두고, 질문 원칙을 이렇게 정리합니다.

추측하지 말 것, 잘못된 패키지나 버전으로 진행하면 무의미한 결과가 나옴

한 번에 하나씩, 패키지와 버전을 동시에 묻지 말고 순서대로 확인

프로젝트 환경이 있으면 질문 최소화, package.json에서 읽을 수 있는 정보는 직접 확인

에이전트가 그럴듯한 추측으로 진행해 엉뚱한 changelog를 요약하는 실패를 막는 규칙입니다. 스킬을 쓰는 쪽에서 보면 사소한 문구지만, 스킬을 만드는 쪽에서 보면 "어디까지 자율적으로 하고 어디서 멈춰 물을 것인가" 를 문서로 못 박은 사례라 그대로 참고할 만합니다.

Agent Skill 더 알아보기

SEED Agent Skill 공식 문서 - SKILL.md와 참조 문서 6개 전문

Claude Agent Skills 공식 문서 - 스킬 형식과 작성 규칙

SEED는 어떻게 여기까지 왔나, V1에서 V3까지

AI 통합이 얹힌 기반은 하루아침에 만들어지지 않았습니다. SEED 팀이 더 당근답게, SEED는 어떻게 진화했나에서 정리한 기록을 보면, 시작은 2021년 6월 무렵 "앱 개발에 날개를 달아줄 지원 라이브러리 모음" 이었습니다. V1은 자주 쓰는 스타일을 모아 둔 반복 제거용 모음집에 가까웠고, V2에서 Foundation과 Component를 지원하며 시스템의 모양을 갖췄습니다.

그런데 V2에는 구조적 약점이 남아 있었습니다. 당근만의 의미를 담은 토큰과 프레임워크의 토큰이 뒤섞여 체계가 흔들렸고, 쓰이지 않는 토큰이 쌓였습니다. 무엇보다 색상이 충분한 명도 대비를 보장하지 못했습니다. 팀은 이를 "접근성의 한계가 시스템의 가장 아랫단에 박혀 있던 셈" 이라고 표현합니다. V3는 그래서 버전 업이 아니라 이 약점을 다시 세우는 대규모 개편이 되었습니다.

접근성을 배려가 아니라 기준으로

V3에서 가장 깊이 다룬 주제는 접근성(Accessibility)이었습니다. WCAG와 APCA 같은 업계 표준을 충족하는 경험을 처음부터 기준으로 삼았고, 가장 구조적인 변화는 색상의 역할을 나눈 것이었습니다. 색을 전경(fg), 배경(bg), 외곽선(stroke)으로 분리하고 일관된 네이밍 체계를 입혀, 그 조합이 언제나 충분한 명도 대비를 보장하도록 만들었습니다.

색상 역할 문서가 정리한 원칙은 명확합니다. 역할 기반 색상(--seed-color-fg-*, --seed-color-bg-*, --seed-color-stroke-*)을 우선 쓰고, 팔레트 색상(--seed-color-palette-*)은 역할로 커버되지 않는 예외에만 씁니다. 에이전트에게 색을 고르게 할 때도 이 규칙이 그대로 적용되므로, 팔레트 값을 직접 하드코딩하는 출력을 규칙 하나로 걸러낼 수 있습니다.

접근성 항목에서 팀이 가장 의미 있게 꼽는 결정은 터치 영역을 스펙으로 정의한 것입니다. Figma 가이드에도, 모든 구현이 공유하는 스펙에도 터치 영역(targetSize)을 기록해, 어느 개발자가 어느 플랫폼에 구현하더라도 같은 의도가 보장되게 했습니다. 권고를 명시적 기준으로 바꾼 셈입니다.

타이포그래피를 38개에서 24개로

타이포그래피는 덜어내는 방향으로 개편했습니다. 텍스트 스타일을 38개에서 24개로 압축해 작업 복잡도를 낮추면서, Medium 굵기를 더해 위계를 표현할 범위는 오히려 넓혔습니다.

핵심은 Scale 토큰의 도입입니다. 기존에는 폰트 스타일에 부여된 역할과 실제 사용이 어긋나 디자인과 개발 사이에 오해가 잦았는데, V3는 용도가 분명한 스타일에만 역할을 부여했습니다. 현재 스케일은 t1(가장 작음)부터 t10(가장 큼)까지이며, CSS 변수 --seed-font-size-t{n}, --seed-line-height-t{n}, --seed-font-weight-* 로 노출됩니다.

고치기 두려운 시스템에서 계속 고쳐도 되는 시스템으로

V3의 구조적 방향을 결정한 질문은 "무엇을 더 추가할까" 가 아니라 "왜 우리는 시스템을 자신 있게 고치지 못할까" 였습니다. 동기화 메커니즘은 있었지만 토큰의 영향도를 추적할 수 없었기 때문입니다. 토큰 하나를 바꾸면 어떤 컴포넌트와 서비스까지 번지는지 알 수 없으니 업데이트가 늘 조심스러웠습니다.

현재 버전은 토큰마다 그것을 쓰는 다른 토큰과 컴포넌트를 역으로 추적할 수 있고, 어떤 서비스까지 영향이 번지는지도 파악해 나가고 있습니다. 팀은 이 변화를 "한때 고치기 싫은 시스템이었던 SEED가 계속 고쳐도 괜찮은 시스템으로 바뀐 것" 이라고 정리합니다.

추적 기반 위에서 동기화도 한 단계 올라섰습니다. 컴포넌트 디자인을 업데이트하면 문서와 각 플랫폼의 구현체가 함께 동기화되고, 구조 변경이 없는 한 모든 플랫폼 구현에 변경이 동시에 전파됩니다. 이 동기화가 있어야 llms.txt와 MCP가 내보내는 문서가 실제 구현과 어긋나지 않습니다. AI 통합의 신뢰도는 결국 이 기반에서 나옵니다.

라이브러리 철학도 함께 바뀌었습니다. 기존 라이브러리는 디자인 통일성을 지키려 커스터마이징을 제한하는 방향으로 설계돼 있었는데, 팀은 통일성은 디자인 단계에서 풀 문제이지 라이브러리가 닫힌 인터페이스로 제약할 일은 아니라고 판단했습니다. 그래서 구성요소를 분해해 제공하는 방식으로 전환했고, 같은 철학이 Figma에서는 Slot과 조합형 컴포넌트로 나타납니다. 폼 컴포넌트 Field를 Header와 Slot, Footer로 나눠 레이블과 설명, 에러 메시지는 Field가 책임지고 실제 입력 요소는 Slot에 끼워 넣게 한 것이 대표적인 예입니다.

프로필 화면으로 증명한 결과

새 기준을 한 번에 갈아타는 대신 Foundation부터 자리 잡게 하고 컴포넌트를 차근차근 올리는 점진적 롤아웃을 택했습니다. Figma 디자인 키트를 배포하고 전사에 소개한 뒤 팀별 온보딩을 거쳤으며, 전환이 어려운 팀은 직접 마이그레이션을 도왔습니다. 팀은 이를 "시스템 전환을 기술 배포가 아니라 조직이 함께 익혀가는 과정으로 본 결정" 이라고 설명합니다.

첫 적용 화면은 프로필이었습니다. fg, bg, stroke로 역할이 나뉜 색상 체계로 정보 우선순위를 다시 잡고, Scale 토큰과 새 타이포 위계로 먼저 볼 것과 나중에 볼 것을 구분했습니다.

결과는 프로필에서 다른 이웃을 모아보기하는 수가 약 44% 증가, 화면 체류 시간이 Android 68%, iOS 83% 증가였습니다. 디자인 시스템 개편을 취향 문제가 아니라 지표로 검증한 사례라, 사내에서 개편을 설득해야 하는 입장이라면 인용할 만한 숫자입니다.

그리고 팀이 다음 챕터로 지목한 것이 바로 AI입니다.

디자인 시스템이 '의사결정의 압축'이라면, 다음 진화는 그 압축을 사람과 도구가 함께 풀어 쓰는 단계라고 생각해요.

문서를 사람만 읽는 참고 자료에서 에이전트도 이해하는 구조로 바꾸는 것, 자연어로 탐색하는 문서 어시스턴트, 아이디어를 바로 화면으로 만드는 프로토타이핑 파이프라인, 패치노트를 일일이 따라가지 않아도 변경이 프로젝트에 반영되는 유지보수 자동화가 실험 중인 항목으로 언급됩니다. 앞서 살펴본 네 개 층이 이 로드맵의 첫 구간에 해당합니다.

디자인 시스템에도 브랜딩이 필요했을까

같은 시기 SEED 팀이 공개한 또 하나의 기록은 디자인 시스템에도 브랜딩이 필요할까입니다. 기술 문서와 결이 다르지만, 오픈소스 프로젝트를 운영하는 입장에서는 오히려 실용적인 내용이 많습니다.

브랜딩팀이 처음 마주한 질문은 사내에서만 쓰는 디자인 시스템에 브랜딩이 정말 필요한지였습니다. 당근 로고는 이미 견고한 자산이니 그대로 쓰고 "당근 디자인 시스템" 이라 부르면 충분해 보였습니다. 생각이 바뀐 계기는 SEED의 사용자를 다시 정의한 데 있었습니다. 누군가는 매일 아침 그것을 열어 보고, 그 안의 결정을 신뢰하고, 본인 작업의 기준으로 삼고 있었습니다. 그렇다면 그것은 도구가 아니라 당근이 만드는 또 다른 제품 이고, 다른 점은 사용자가 이웃이 아니라 함께 일하는 디자이너와 엔지니어라는 것뿐이었습니다.

글은 디자인 시스템을 굳이 외부에 공개하는 이유를 세 가지로 정리합니다. 내외부 피드백을 받는 열린 구조, 제품을 잘 만들고 잘 관리하는 팀이라는 신호, 그리고 그 신호가 채용으로 이어지는 흐름입니다. 실제로 SEED는 공개 이후 GitHub에서 별 800개를 넘겼고(현재는 960개), 채용 면접에서 지원자가 먼저 언급하는 일도 잦았다고 합니다. 오픈소스 문서화에 드는 비용을 조직에 설명해야 할 때 쓸 수 있는 논거입니다.

브랜딩 방향을 잡을 때 부딪힌 질문은 SEED가 누구에게 어떤 태도로 말하는가였습니다. 킥오프에서 나온 한 문장이 이 지점을 갈랐습니다. 프로덕트와 프로덕트를 만드는 사람들은 다르다는 것이었습니다. 사용자가 만나는 것은 완성된 프로덕트지만, 디자인 시스템과 대화하는 대상은 그 프로덕트를 만드는 전문가들입니다. 그래서 당근 앱의 친근한 인상을 그대로 확장하는 대신, 전문적이고 믿음직한 결을 따로 만들어야 했습니다.

로고와 컬러를 그리기 전에 먼저 한 일은 무엇을 담을지 정의하는 것 이었습니다. 컬처덱과 인재상에서 나온 조직문화의 언어, 모브랜드의 언어, SEED가 제품 차원에서 추구하는 언어를 카테고리별로 펼쳐 놓고, 유저를 향하는 말과 구성원을 향하는 말로 나눈 뒤 양쪽을 아우르는 지점을 찾았습니다. 그렇게 추려낸 세 가지 핵심 가치는 공교롭게도 당근이 오랫동안 지켜온 브랜드 가치와 같은 이름으로 수렴했습니다.

Local: 당근 프로덕트를 이루는 가장 작은 단위인 SEED. 토큰 하나, 컴포넌트 하나에서 출발하는 하이퍼로컬의 시작점입니다.

Connect: 당근의 구성원이 협업하고 연결되는 방식인 SEED. 디자이너와 엔지니어가 함께 쓰는 공통의 언어이자 일하는 방식입니다.

Life: 당근이 성장할수록 같이 자라고 진화하는, 살아있는 생태계로서의 SEED입니다.

같은 단어를 쓰되 디자인 시스템이라는 제품의 관점에서 다시 정의한 것이 요점입니다. 이 셋이 이후 모든 결정의 기준이 되었고, 판단의 이정표는 늘 "이게 이 셋을 잘 드러내는가" 였습니다.

브랜드 컨셉의 중심에는 이름 그대로 씨앗이 있습니다. 작은 점 하나에서 컴포넌트가 만들어지고, 컴포넌트가 모여 스크린이 되고, 스크린이 모여 프로덕트가 되고, 끝내 당근이라는 브랜드가 완성됩니다. 이 흐름을 압축한 슬로건이 "Seed to Root, Root to Daangn" 입니다.

로고의 단순한 실루엣에는 세 가지 의미가 겹쳐 있습니다. 위에서 내려다본 동네를 닮은 하이퍼로컬 지도, 점과 점이 이어져 네트워크를 이루는 연결의 선, 그리고 뿌리이자 컴포넌트가 가지를 뻗는 디자인 시스템의 구조입니다. 마지막 항목은 당근 앱 화면에서 UI 블록과 블록 사이의 빈 공간, 이른바 네거티브 영역에서 비롯된 형태입니다.

무엇을 택하지 않았는지도 함께 밝혀 두었습니다. 별이나 꽃 형태는 AI 서비스들이 워낙 많이 써서 차별화가 어려웠고, 다리(bridge)는 연결을 뜻하기엔 흔하고 중공업적인 인상이었으며, 위빙(weaving)은 데이터 알고리즘만 강하게 연상됐습니다. 텍스트버블이나 콜론 기호는 메신저 서비스에 더 어울렸습니다. 후보를 덜어낸 과정을 남긴 것 자체가 참고 자료가 됩니다.

컬러에서는 주황을 덜어내자는 의견과 익숙함에서 멀어지는 것을 우려하는 의견이 맞붙었고, 결론은 주황을 지키면서 코드 에디터 하이라이트에서 따온 라임 컬러를 포인트로 더하는 방향이었습니다. 주황이 당근다움을, 라임이 디자인 시스템다운 전문성을 맡는 배분입니다. 글은 이 긴장을 없앨 문제가 아니라 끝까지 안고 갈 좌표로 봅니다.

좋은 디자인 시스템이 디자이너의 수많은 의사결정을 대신 정리해준다면, 좋은 브랜딩은 그 시스템을 '믿고 쓰게' 만들어줍니다.

한국 개발자가 SEED에서 가져갈 수 있는 것

SEED 사례에서 자기 프로젝트에 바로 옮길 수 있는 부분을 정리하면 다음과 같습니다.

층을 나누어 점진적으로 열기: 네 개 층 전부를 만들 필요는 없습니다. llms.txt는 문서 사이트 빌드 파이프라인에 텍스트 출력 하나만 더하면 되므로 비용이 가장 낮고, 도구 설치 없이 즉시 효과가 납니다. 인덱스와 전문을 나누는 SEED 방식만 따라도 컨텍스트 낭비를 크게 줄일 수 있습니다. MCP 서버는 그다음이고, Agent Skill은 워크플로가 안정된 뒤에 얹는 편이 순서에 맞습니다.

규칙적인 주소가 검색을 대체한다: /llms/react/components/{name}.txt처럼 예측 가능한 주소 규칙을 두면 에이전트가 검색 왕복 없이 문서를 곧장 가져옵니다. 벡터 검색을 붙이는 것보다 싸고 정확합니다.

CLI는 데이터, 스킬은 해석: 업그레이드 진단에서 SEED가 택한 분업은 다른 도구에도 그대로 적용됩니다. 결정론적으로 처리할 수 있는 데이터 수집은 CLI에 두고, 프로젝트 맥락에 따라 달라지는 판단만 LLM에 남기면 재현성과 비용이 함께 개선됩니다.

출력을 검증하는 게이트를 만들기: compat 명령이 불일치를 종료 코드 1 로 알리는 구조는 에이전트가 생성한 코드를 CI에서 걸러내는 장치가 됩니다. 에이전트에 문서를 열어 줄 때 검증 경로를 함께 만드는 것이 신뢰의 전제입니다.

동기화 없는 문서 공개는 위험하다: 토큰 영향도 추적과 구현 동기화가 갖춰지지 않은 상태에서 문서를 기계에 노출하면, 에이전트가 실제 구현과 어긋난 코드를 확신을 갖고 생성합니다. SEED가 V3에서 동기화 기반을 먼저 세운 뒤 AI 통합을 얹은 순서에는 이유가 있습니다.

한 가지 덧붙이면, SEED 문서가 대부분 한국어로 작성되어 있다는 점도 국내 팀에게는 실질적인 이점입니다. 아이콘 검색이 한국어 키워드를 받는 것처럼, 한국어로 질문하는 워크플로를 처음부터 전제하고 만든 몇 안 되는 공개 디자인 시스템입니다.

당근 디자인 시스템 SEED 홈페이지

SEED AI & Tools 문서

더 당근답게, SEED는 어떻게 진화했나

디자인 시스템에도 브랜딩이 필요할까

SEED Design GitHub 저장소

라이선스

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

이 글이 유용하셨다면 아래쪽 좋아요를 눌러주세요 — 파이토치 한국 사용자 모임이 새로운 소식을 정리하고 공유하는 데 힘이 됩니다!