「예비 지식이 없는 AI가 문서(docs)만으로 스스로 구축할 수 있다」는 것을 설계 목표로 삼은 디자인 시스템

을 공개했습니다. 이 기사는 프로덕트 소개입니다——@gunjo/ui

(군청) 무엇이 들어있고, 어떻게 사용할 수 있으며, 다른 것과 무엇이 다른가. 검증의 이야기(170개 화면의 콜드 테스트 연재)는 별도 기사의 총집편에 정리되어 있으므로, 이 기사에서는 골자만 다룹니다.

이게 뭔가요

npm 패키지:@gunjo/ui

(0.1.0-beta.1) — React 19 / Tailwind v4 -
문서(docs): gunjo.jp -
소스: github.com/uixhero/gunjo (MIT)

npm i @gunjo/ui

import { Button, DataTable, AmountBreakdown } from "@gunjo/ui";

하나의 typed entry point로부터, **205개의 컴포넌트(component)**가 TS 타입과 함께 제공됩니다.

안에 들어있는 것

범용 컴포넌트

Button / Form / DataTable / Tabs / Dialog / Toast / CommandPalette / Chart 군……의 이른바 기본 세트. 특징은 딱 두 가지입니다:

차트는 HTML/CSS 레이아웃으로 구성되어 있습니다 (SVG가 아님). 목표는 「임의의 데이터에서도 레이아웃이 깨지지 않는 것」입니다. 차원이 다른 스케일, 이상치, 제로, 극소값을 넣어도 파손되지 않는 쪽을 지향합니다 -
Form은 context 협조형입니다. FormField가 id / aria-invalid / aria-describedby를 자동으로 주입하므로, 검증(validation) UI의 접근성(a11y) 배선을 직접 작성할 필요가 없습니다

업무 도메인 컴포넌트

군청(gunjo)의 특색은 이 부분입니다. 실제 업종의 화면에서 탄생한 업무용 컴포넌트가 처음부터 포함되어 있습니다:

금액:AmountBreakdown (내역 → 중간값 → 최종값 도출 표시) ・ EditableDataTable ・ CurrencyInput -
책임이 무거운 조작:ScanGate (3점 인증) ・ CoSign (2인 확인) ・ SignedRecord (서명 → 잠금 → 추가만 가능) ・ SafetyBanner ・ ApprovalWorkflow -
값의 판정:ReferenceValue (기준값 · H/L) ・ Meter (용량) ・ ExpiryBadge (기한) ・ LimitMonitor (이름이 지정된 상한선) -
현장 오퍼레이션:StatusBoard (상태 보드) ・ ActionQueue (대응 필요 큐) ・ Stringline (시간 × 거리 운행 도표) ・ RouteStops ・ Leaderboard -
사람과 조직:PersonCell ・ RelationshipRow ・ CompanyCell ・ MatchCard (두 대상의 조합) -
모바일 B2C:PageHeader (앱 바) ・ BottomActionBar (하단 고정 CTA) ・ TicketStub (티켓 면) ・ SeatMap ・ LoyaltySummaryCard -

「관리자 화면 키트」도 「마케팅 사이트 키트」도 아닌, 업무 시스템 그 자체를 구축하기 위한 컴포넌트군을 지향합니다.

패턴과 토큰

패턴 집합: 인증 · 대시보드 · 에디터 · kanban · 미디어 라이브러리 등, 컴포넌트를 조합한 완성형 -
디자인 토큰(design token): 색상(군청 · 코차) · 타이포그래피 · 모서리 곡률 · 그림자 · 애니메이션. 모두 기계 판독 가능한 spec 포함

「AI가 사용할 수 있도록」 하기 위해 무엇을 했는가

보통의 디자인 시스템은 인간의 시선에서 작성됩니다. AI 에이전트에게 사용하게 하려고 하면, 이름으로 검색해도 목적의 컴포넌트에 도달하지 못하거나 · prop을 추측할 수 없거나 · docs의 구조를 해석하지 못해 막히게 됩니다. 군청은 처음부터 여기에 투자했습니다:

typed entry point—import { ... } from "@gunjo/ui"

모든 컴포넌트가 TS(TypeScript) 타입이 적용되어 있습니다. 에이전트는 타입 정의를 읽고 API를 확정할 수 있습니다. -
기계 가독성 메타데이터 (Machine-readable metadata)— 각 컴포넌트에 use-case(사용 사례)・API shape(API 형태)・variant key(변형 키)가 구조화된 데이터로 부착되어 있습니다. -
사용 사례별 대응표 (by-use-case)— "하고 싶은 일"로부터 컴포넌트에 도달할 수 있는 대응표입니다. "없음"을 솔직하게 적는 것이 특징입니다 (없다는 사실을 숨기는 것보다, 잘못된 컴포넌트를 추천하지 않는 것이 더 안전하기 때문입니다). -
AI-handoff docs— gunjo.jp의 문서는 LLM이 그대로 "읽고 사용함"을 전제로 형식을 맞추어 작성되었습니다.

정말로 쓸 수 있는지는 170개 화면으로 검증했습니다

……라고, 여기까지는 주장입니다. 쓰는 것만이라면 누구나 쓸 수 있습니다.

그래서, 군청(Gunjo)을 한 번도 본 적 없는 사전 지식 제로의 AI에게, 공개된 docs와 npm 패키지만을 전달하여 실제 업종의 화면(은행·의료·물류·철도·택시…) 170개를 계속해서 구성하게 했습니다. AI가 "이 컴포넌트가 없어서 직접 구현했다"라고 솔직하게 보고한 부분만을 컴포넌트로 만든다——이 검증 루프의 모든 기록이 공개되어 있습니다:

• gunjo.jp/cold-tests— 170개 화면의 상설 카탈로그 (20개 카테고리의 인덱스 페이지·AI가 작성한 소스 코드·해설 포함) -
• 왜 콜드 테스트(Cold Test)를 하는가— 방법론 페이지 -
• 총집편 (Zenn)— 170개 화면을 통해 발견한 내용의 요약

위에 언급한 업무용 컴포넌트는 전부, 이 검증에서 "3회 독립적으로 직접 구현된" 것만을 정식으로 만든 결과입니다. 상상으로 만든 컴포넌트는 없습니다.

앞으로

• @gunjo/ui는 현재 기능이 갖춰지고 API를 확정하기 시작하는 단계에 진입했습니다 (0.1.0-beta.1). (이후 파괴적 변경(Breaking changes)은 마이너 업데이트로만 진행하며, 마이그레이션 경로를 제시합니다.)
• 콜드 테스트 연재는 계속됩니다. X(구 Twitter)에서 "오늘의 콜드 테스트"를 주 2~3회 게시할 예정입니다.
• 피드백은 GitHub Issues로 부탁드립니다. "이 업종의 이 화면을 구성할 수 없다"라는 보고가 가장 반갑습니다.

괜찮으시다면 한 번 사용해 보세요.

이 기사는 작성자가 AI(Claude)와 협업하여 제작하고 있습니다. 실험·검증의 설계, 판단, 공개 전의 사실 확인은 인간이 수행하며, 실무 작업과 초안 작성은 AI가 담당합니다.

GunjoUI by UIXHERO

Discussion