date
slug
author
status
tags(최대 3개)
summary
type
thumbnail
category
updatedAt
들어가며
지금까지 디자인 시스템의 주 사용자는 사람이었습니다. 아임웹의 디자인 시스템도 개발자 경험, 즉 DX(Developer eXperience)를 기준으로 삼았습니다. 이제는 AI 에이전트도 디자인 시스템을 읽고 코드와 디자인을 만듭니다. 그래서 이번 개편에서는 에이전트가 디자인 시스템을 해석하고 사용하는 경험, 즉 AX(AI eXperience)에 집중했습니다.
AX를 위해 무엇을 바꿨고 그 과정에서 무엇을 얻었는지 정리합니다.
*일반적으로 AX는 AI Transformation으로 통용되지만, 이번 글에선 AI eXperience로 정의합니다.
디자인 시스템은 에이전트의 소통 언어
기존 디자인 시스템은 통일된 디자인과 사용성으로 사람 사이의 소통 비용을 줄이는 데 집중했습니다.
에이전틱 AI가 업무에 들어오면서 상황이 달라졌습니다. 실무자는 코드와 디자인 산출물을 하나씩 확인하는 대신 에이전트에게 맡깁니다. 디자인 시스템의 주 사용자가 사람에서 에이전트로 넓어졌습니다. 에이전트는 디자인 시스템을 언어처럼 써서 디자인과 코드를 양방향으로 오갑니다.
이미 여러 AI 디자인 도구가 디자인 시스템 연결을 권장합니다.
새 패키지로 다시 설계하기
‘Clay’는 메이저 버전 2까지 올라온 아임웹 디자인 시스템입니다. 그런데 컴포넌트마다 API가 제각각이라 에이전트가 추측해야 할 것이 너무 많았습니다. 사실 사람에게도 이미 불편한 구조였습니다.
그래서 기반부터 새로 설계하고, 새 패키지를 만들기로 했습니다. 목표는 두 가지였습니다. 컴포넌트 사이의 일관성을 갖추는 것, 그리고 무엇을 언제 써야 하는지 분명히 하는 것입니다.
어휘와 구조 통일하기
레거시 Clay는 컨벤션이 모호해 명칭이 분산돼 있었습니다. 설명 텍스트는
description과 helperText가 공존했고 타입도 string과 ReactNode로 갈렸습니다. 구조 역시 flat과 compound가 섞여 있었습니다.컨벤션을 명확히 정의하고 전 컴포넌트를 같은 패턴으로 다시 만들었습니다. 상태 prop은 HTML 표준 속성명으로 맞췄고 구조는
compound로 통일했습니다.어휘와 구조를 통일한 이유는 에이전트가 컴포넌트마다 다른 패턴을 새로 파악하지 않게 하기 위해서입니다. 패턴이 다르면 매번 문서를 다시 조회해야 하고 그 비용이 곧 컨텍스트 소모와 환각으로 이어집니다.
Figma와 React: 같은 이름, 같은 속성
이전에는 Figma를 디자이너 전용, React를 개발자 전용으로 여겼습니다. 이제는 두 영역을 나눠 둘 이유가 없습니다. 디자인 시스템으로 둘을 묶어 Figma와 React를 자유롭게 오가고 싶었습니다.
그래서 양쪽의 구조와 명칭을 통일했습니다. 같은 이름, 같은 속성과 값, 같은 구조를 쓰도록 Figma와 React 컴포넌트를 동일한 규칙으로 리팩터링했습니다. 에이전트가 해석하는 단계에서 디자인과 개발 사이의 간극을 줄이려는 목적입니다.
Figma의 layer 이름과 React 컴포넌트 이름이 같고 속성명과 값의 타입까지 맞췄습니다.
<Checkbox size="medium" checked> <Checkbox.Label>개인정보 처리방침 동의 (필수)</Checkbox.Label> <Checkbox.Description>서비스 제공 목적에만 사용됩니다.</Checkbox.Description> </Checkbox>
가이드라인 제공
구조와 명칭이 일관돼도 에이전트가 모든 것을 알 수는 없습니다. 특히 언제 어떤 컴포넌트를 써야 하는지, 상황에 맞는 조합이 무엇인지는 코드만 보고 판단하기 어렵습니다.
그래서 가이드라인 79개를 작성했습니다. 진입점인
root.md가 읽는 순서와 공통 규칙을 정하고, 개요와 공통 개념, 디자인 토큰, 그리고 모든 컴포넌트의 사용법을 문서로 제공합니다.clay guideline ├── root.md 진입점 ├── overview-*.md 개요 │ ├── overview-components.md │ ├── overview-tokens.md │ └── ... │ ├── concept-*.md 공통 개념 │ ├── concept-props.md │ ├── concept-composition.md │ └── ... │ ├── design-tokens/ Foundation 정보 │ ├── colors.md │ ├── typography.md │ └── ... │ └── components/ 개별 컴포넌트 ├── button.md ├── select.md └── ...
에이전트는 코드를 쓰기 전에 이 문서들을 읽고 판단 기준을 세웁니다.
root.md는 첫 줄부터 에이전트를 독자로 삼습니다.# Clay UI 가이드라인 Clay UI 사용 가이드라인. AI agent는 코드 작성 전 아래 워크플로우와 규칙을 따릅니다. ## 워크플로우 1. 개요 읽기 2. 디자인 토큰 읽기 3. 컴포넌트 가이드라인 읽기 4. 아이콘 검증 ## 규칙 - ✅ 항상 `@imwebme/clay-ui` 컴포넌트를 우선 사용 - ❌ Clay 컴포넌트에 `className` 추가 - ❌ Tailwind 클래스로 레이아웃 구성 — `<Flex>`, `<Stack>` 같은 layout 컴포넌트 사용
제품 개발자의 에이전트는 Clay CLI로 가이드라인을 조회합니다. 터미널에서
clay usage Button처럼 명령을 실행하면 해당 컴포넌트의 사용법과 props 시그니처, 예제를 바로 확인할 수 있습니다.사내 생산성 도구에도 같은 가이드라인이 들어갑니다. 제품 코드를 쓰는 에이전트와 도구 안의 에이전트가 같은 규칙을 따르니 어디서 만들든 결과물이 같은 기준을 지킵니다.
측정 결과: 타입 에러 0건, 비용 절반
구조와 명칭을 통일하고 가이드라인을 제공한 효과를 확인했습니다. 같은 화면 과제 5개를 레거시 Clay와 새 Clay로 각각 3번씩 에이전트에게 맡겨 비교했습니다.
레거시에서 반복된 오류는 대부분 명칭 추측이었습니다.
Switch의 isChecked를 checked로 쓰거나, Textfield를 TextField로 import하는 식입니다. 상태 prop을 HTML 표준 속성명으로 맞춘 것도 이런 오류를 막기 위해서였습니다.규약이 명시돼 있으면 에이전트가 추측할 지점이 줄어듭니다. 문서를 뒤지거나 틀려서 되돌아가는 일이 줄어든 만큼, 완성까지 걸린 시간과 비용도 절반 가까이 내려갔습니다.
Clay 위에서 만드는 도구들
Clay는 이제 에이전트가 읽을 수 있는 디자인 시스템이 됐고 디자인과 개발 사이의 언어 역할을 맡습니다. 디자인을 코드로 옮길 때도, 코드를 디자인으로 되돌릴 때도 Clay가 기준이 됩니다. 디자이너와 엔지니어가 같은 이름으로 이야기할 수 있습니다.
아임웹에서는 Clay를 활용한 AI 생산성 도구를 개발하고 있습니다. 대표적으로 에이전틱 프로토타이핑 도구 ‘mold’가 있습니다. 대화만으로 아임웹 프로토타입을 만들어 주는 도구인데, Clay 컴포넌트를 그대로 조합하기 때문에 결과물이 실제 제품과 같은 형태로 나옵니다.
디자인과 코드를 잇는 순환 구조
초석은 다졌습니다. 이제 이 규약을 참조하는 도구를 넓혀갈 차례입니다.
디자이너는 Figma에서, 엔지니어는 코드에서 각자의 자리에 앉아 에이전트에게 일을 맡깁니다. 화면을 조립하는 것도, 프로토타입을 만드는 것도, 레거시를 옮기는 것도 결국 같은 언어를 쓰는 작업입니다. 앞으로 만들 생산성 도구도 모두 같은 규약을 참조합니다.
디자인 시스템 자체를 다루는 일도 자동화하고 있습니다. 라이브러리 업데이트로 오버라이드가 사라지는 문제를 해소하고, 레거시 마이그레이션을 각 팀이 스스로 할 수 있게 만드는 일이 우선입니다. 모든 컴포넌트가 같은 규약을 따르니 새 컴포넌트를 만드는 작업도 이어서 맡길 수 있습니다.
더 멀리 보면 순환 구조를 만들고 싶습니다. 지금은 디자인이 바뀌면 코드, 가이드라인, 테스트, 도구까지 하나하나 직접 고쳐야 하고, 하나라도 놓치면 그 지점부터 어긋납니다. 어디서 시작한 변경이든 나머지로 전파되고 마지막에 다시 Figma로 돌아오게 만드는 것이 다음 과제입니다.
디자인 시스템을 운영하는 팀이라면 머지않아 같은 질문을 만납니다.
우리 시스템은 사람만 읽을 수 있는가, 아니면 에이전트도 읽을 수 있는가
작업을 해 보니 에이전트를 이해하려는 노력이 시스템 자체를 더 단단하게 만들었습니다. 에이전트가 읽기 쉬운 구조는 결국 사람도 읽기 쉬운 구조였습니다.
박종준 Frontend Engineer
디자인 시스템을 좋아하고, 생산성을 높이는 데 집중합니다.
일은 즐거워야 하고, UI는 예쁘고 쓰기 편해야 합니다.