프로젝트 소개
open-claude-ui는 최신 데스크톱 AI 클라이언트를 위한 오픈 소스 UI 컴포넌트 라이브러리이자 모션 엔진입니다. 이 프로젝트는 REA 리버스 엔지니어링 프레임워크를 기반으로 정적 AST 분석, 클로저 코드 난독화 해제, 런타임 추적 및 ASAR 리소스 해체를 수행하고, 연구 결과를 재사용 가능한 React 컴포넌트, Hooks, 테마 스타일 및 기술 문서로 정리했습니다.
단순히 인터페이스 외관만 복제하는 것이 아니라, 상호작용의 완성도에 영향을 주는 엔지니어링 메커니즘도 중점적으로 복원합니다. 예를 들어 물리 스프링 파라미터, CJK 입력기 보호, 스크롤 가장자리 페이드, 스트리밍 메시지 스크롤 제어, 커서 기준 확대/축소, 드래그 임계 영역 및 Web Audio 합성 알림음 등이 포함됩니다.
준법 안내: 프로젝트는 상용 글꼴이나 녹음 파일 등의 독점 바이너리 자산을 배포하지 않으며, 시스템 글꼴 폴백 스택과 Web Audio API 기반의 순수 코드 음향 효과를 사용합니다. 프로젝트는 MIT License를 따르며, 관련 결과물은 학습, 연구 및 엔지니어링 교류를 위해 사용됩니다.
적합한 프로젝트
AI 채팅 클라이언트, 모델 콘솔, 도구 호출 승인 인터페이스, 데스크톱 어시스턴트, 미디어 뷰어 또는 멀티 에이전트 협업 공간을 개발 중이라면 이 저장소에서 필요한 컴포넌트를 선택해 도입할 수 있습니다. 시각적 토큰과 복잡한 상호작용을 직접 다시 디버깅할 필요가 없습니다.
- Web AI 애플리케이션: 세션 버블, 서식 있는 텍스트 입력창, 모델 전환기 및 Token 대시보드를 사용합니다.
- 스트리밍 생성 인터페이스: 스크롤 핀, 사고 과정 접기 및 페이드 마스크를 사용합니다.
- 데스크톱 애플리케이션: Electron 창 팩토리, macOS 제목 표시줄 및 Vibrancy 머티리얼 방식을 사용합니다.
- Artifacts 및 멀티미디어 애플리케이션: 분할 패널 드래그, 미디어 라이트박스, 공유 요소 전환 및 iframe 샌드박스 브리지를 사용합니다.
- 접근성 애플리케이션: WAI-ARIA 방식을 따르는 Roving TabIndex 포커스 이동 Hook을 사용합니다.
핵심 기능
디자인 토큰 및 시각 체계
프로젝트는 Surface 0부터 Surface 3까지의 저대비 표면 단계, 테라코타 오렌지 #d97757, 고해상도 화면의 헤어라인 경계 보정, 시스템 글꼴 폴백 스택, 버튼·패널·버블·입력창을 위한 모서리 반경 매트릭스를 제공합니다. 전역 테마 변수와 핵심 프레임은 code-examples/cds-theme.css에 모아 두었습니다.
30개의 독립 코드 모듈
저장소에는 11개의 기본 원자 컨트롤과 19개의 아키텍처 또는 상호작용 모듈이 포함되어 있습니다. 컴포넌트 소스는 code-examples에 있으며, 통합 TypeScript export 진입점은 src/index.ts입니다. 이 모듈은 버튼, 세그먼트 선택, 입력창, 세션 버블, MCP 의사 결정 카드, 미디어 뷰어, 스트리밍 Diff, 데스크톱 창 및 멀티 에이전트 캔버스 등의 시나리오를 다룹니다.
프로덕션 수준의 상호작용 메커니즘
- Bouncy, Snappy, Gentle, Heavy Snap을 포함한 4가지 물리 스프링 프리셋을 제공합니다.
- 스크롤 영역은 7단계 비선형 Alpha 마스크를 사용하며, 상단 또는 하단에 닿았는지에 따라 동적으로 조정됩니다.
- 입력창은
isComposing과keyCode === 229의 이중 조건으로 CJK 입력기를 보호합니다. - 스트리밍 출력은 하단 40px 허용 오차와 150ms의 수동 스크롤 냉각 시간을 사용해 자동 스크롤이 뷰포트를 강제로 빼앗지 않도록 합니다.
- 마이크 파형에는 8% 노이즈 게이트 임계값과 0.7 제곱 감마 압축을 적용합니다.
- 드래그 및 갤러리 상호작용에는 4px 포인터 이동 임계 영역을 적용해 손의 미세한 흔들림을 걸러냅니다.
오프라인 컴포넌트 미리보기
저장소에는 단일 파일로 구성된 대화형 스토리북 docs/claude-components-storybook.html이 포함되어 있습니다. 로컬 개발 서버를 시작하지 않아도 테라코타 색상 체계, 다크 모드, 버튼 피드백, 세그먼트 캡슐, 스프링 애니메이션, 첨부 파일 타일 및 복사 상태 애니메이션을 확인할 수 있습니다.
설치 및 환경 준비
기술 스택 확인
저장소 표기에 따르면 다음 환경을 갖추는 것이 좋습니다.
- React 18 이상.
- TypeScript 5.5 이상.
- Tailwind CSS 3.4 이상.
- Framer Motion 11 이상.
README에는 특정 패키지 관리자의 설치 명령이 제공되어 있지 않습니다. 시작하기 전에 작업 공간, Git 의존성 또는 패키지 배포 방식에 따라 open-claude-ui 경로로 프로젝트에 접근할 수 있도록 구성하고, 위의 동급 기술 스택이 모두 설정되어 있는지 확인해야 합니다.
먼저 오프라인 스토리북 확인
저장소 소스 코드를 이미 확보했다면 미리보기 파일을 바로 열어 볼 수 있습니다.
open docs/claude-components-storybook.html비즈니스 프로젝트를 수정하지 않고도 이 단계를 통해 컴포넌트의 시각적 효과, 다크 테마 및 상호작용 애니메이션이 프로젝트 요구 사항에 맞는지 확인할 수 있습니다.
테마 스타일 구성
전역 CSS 가져오기
애플리케이션의 전역 스타일 진입점에서 CDS 테마 파일을 가져옵니다. 이 파일에는 CSS 사용자 지정 속성과 컴포넌트에 필요한 핵심 프레임이 포함되어 있습니다.
@import "open-claude-ui/code-examples/cds-theme.css";이 테마는 표면 색상, 테라코타 브랜드 색상, 테두리, 그림자 및 애니메이션 기반을 제공합니다. 컴포넌트 간 일관성을 유지하려면 기존 CSS 변수를 우선 사용하고, 각 컴포넌트에서 색상을 하드코딩해 반복하지 않는 것이 좋습니다.
Tailwind 구성 확장
프로젝트의 tailwind.config.js에서 저장소가 제공하는 테마 확장을 불러옵니다.
const cdsTheme = require("open-claude-ui/code-examples/tailwind.config.js");
module.exports = {
content: [
"./src/**/*.{js,ts,jsx,tsx}",
"./node_modules/open-claude-ui/**/*.{js,ts,jsx,tsx}"
],
theme: {
extend: {
...cdsTheme.theme.extend
}
}
};content 배열은 애플리케이션 소스와 open-claude-ui 내 Tailwind 클래스명이 포함된 파일을 모두 포함해야 합니다. 그렇지 않으면 프로덕션 빌드에서 컴포넌트가 사용하는 유틸리티 클래스가 생성되지 않을 수 있습니다.
기본 사용법: 모델 제어 및 채팅 입력 영역 구성
다음 예제는 세 가지 핵심 모듈을 조합합니다.
ScrollFadeContainer는 스크롤 영역의 위아래 가장자리에 페이드를 추가합니다.ModelSwitcherWithTokenGauge는 모델 선택, Extended Thinking 상태 및 Token 예산을 표시합니다.ChatComposer는 핵심 메시지 입력과 전송 콜백을 제공합니다.
import React, { useState } from 'react';
import {
ChatComposer,
ModelSwitcherWithTokenGauge,
ScrollFadeContainer
} from 'open-claude-ui';
export function App() {
const [model, setModel] = useState<
'sonnet-3.5' | 'haiku-3.5' | 'opus-3'
>('sonnet-3.5');
const [thinking, setThinking] = useState(true);
return (
<div className="flex h-screen w-full bg-[var(--cds-surface-1)]">
<ScrollFadeContainer
axis="vertical"
fadeSize={32}
className="flex-1 p-6"
>
<div className="mx-auto max-w-3xl space-y-4">
<ModelSwitcherWithTokenGauge
currentModel={model}
onModelChange={setModel}
extendedThinking={thinking}
onThinkingChange={setThinking}
tokenBudget={{
inputTokens: 12400,
outputTokens: 3200,
cacheReadTokens: 48000,
cacheWriteTokens: 16000,
maxContextWindow: 200000
}}
/>
<ChatComposer
onSend={(text) => console.log('Send message:', text)}
/>
</div>
</ScrollFadeContainer>
</div>
);
}상태 관리 이해
currentModel과 extendedThinking은 모두 애플리케이션 계층에서 관리하므로 모델 전환기를 실제 모델 요청 구성과 동기화할 수 있습니다. 예제의 tokenBudget은 입력, 출력, 캐시 읽기, 캐시 쓰기 및 최대 컨텍스트 창을 각각 대시보드에 전달합니다.
예제에서 ChatComposer의 onSend는 로그만 출력합니다. 실제 프로젝트에 연결할 때는 이 콜백에서 세션 서비스를 호출하고, 메시지 목록을 업데이트하며, 스트리밍 응답 상태를 시작할 수 있습니다.
일반적인 컴포넌트 선택 가이드
기본 컨트롤
CdsButton: XS, SM, MD, LG의 4가지 크기와 Primary, Secondary, Ghost, Outline, Danger의 5가지 변형을 제공합니다.SegmentedControl: 모드 전환에 사용하며, 순수 기하학적 위치 지정과 Framer MotionlayoutId애니메이션 방식을 지원합니다.StatusIndicators: 테라코타 브리딩 라이트, 실시간 활동 펄스, 사고 3점 애니메이션 및 스켈레톤 광택 효과를 포함합니다.ConfirmationDialog: 일반 또는 위험한 작업의 확인에 사용하며, 블러 마스크와 키보드 포커스 제한을 포함합니다.AttachmentCard: 데스크톱 타일과 입력창 인라인 캡슐의 두 가지 첨부 파일 표시 방식을 지원합니다.
세션 및 도구 호출
ChatMessageBubbles: 사용자 버블과 어시스턴트의 투명한 타이포그래피를 구분합니다.ThinkingAccordion: 접을 수 있는 사고 과정을 표시하며, 생성 중에는 강제로 펼친 상태를 유지할 수 있습니다.RichComposerWithMentions:/명령,@컨텍스트 및 Token 예측이 필요한 입력 터미널에 적합합니다.McpToolDecisionCard: 도구 승인 흐름에 사용하며,pending_approval,running,success및error상태를 지원합니다.
미디어, 코드 및 Artifacts
MediaLightboxViewer: 75vw 갤러리 트랙, 커서 기준 Pan/Zoom, 드래그 임계 영역 및 Ctrl 휠 확대/축소를 제공합니다.ArtifactsSplitPaneResizer: 양분 패널 크기 조정, 가장자리 접기, 더블클릭 50/50 스냅 및 iframe 포인터 이벤트 간섭을 처리합니다.EpitaxyIframeBridge: Origin 검증과 격리된postMessageRPC 프로토콜을 통해 미리보기 샌드박스에 연결합니다.StreamingDiffViewer: 증분 스트리밍 추가와 통합 및 분할 화면의 두 가지 Diff 모드를 지원합니다.CodeBlock: 코드 컨테이너와 2.5초 복사 상태 페이드아웃을 제공합니다.
고급 활용
중국어·일본어·한국어 입력기 보호
채팅 입력창에서 키보드 이벤트를 직접 확장해야 한다면 입력기 조합 보호를 반드시 유지해야 합니다. 사용자가 병음 또는 가나 후보 창에서 Enter를 눌렀을 때 메시지가 전송되어서는 안 됩니다. 프로젝트에서는 이중 검사를 사용합니다.
const composing =
event.nativeEvent.isComposing || event.keyCode === 229;
if (event.key === 'Enter' && !composing) {
// 메시지 전송
}Escape 키의 경우에도 입력기 후보 창을 닫을 때 이벤트가 계속 버블링되어 대화 창이 실수로 닫히지 않도록 해야 합니다.
스트리밍 출력으로 스크롤 위치를 빼앗지 않기
계속 추가되는 Token은 useClaudeScrollPinning으로 관리할 수 있습니다. 핵심 전략에는 40px 하단 허용 오차, 150ms 수동 스크롤 냉각 시간, 35vh 탄력 버퍼가 포함됩니다. 사용자가 하단 근처에 머무는 동안에는 화면이 출력을 따라갈 수 있지만, 사용자가 직접 위로 스크롤해 이전 메시지를 탐색하기 시작하면 자동 스크롤이 즉시 뷰포트를 하단으로 되돌려서는 안 됩니다.
애니메이션 프리셋 통일
프로젝트는 ClaudeMotionPresets.ts에 조정이 완료된 네 가지 스프링 설정을 제공합니다. 새 컴포넌트를 개발할 때는 애니메이션마다 강성과 감쇠를 임의로 설정하기보다 Bouncy, Snappy, Gentle 또는 Heavy Snap을 우선 재사용해야 합니다. 이렇게 하면 버튼, 패널, 드래그 스냅 및 공유 요소 전환에서 일관된 물리적 언어를 유지할 수 있습니다.
iframe 분할 창 드래그 올바르게 처리하기
분할 막대를 iframe 위로 드래그하면 iframe이 포인터 이벤트를 가로채 드래그가 중단될 수 있습니다. ArtifactsSplitPaneResizer는 드래그가 활성화될 때 이벤트 가로채기 방지 기능을 활성화하고, 4px 이동 임계값, 가장자리 제약, 더블 클릭 중앙 스냅을 함께 적용합니다. 애플리케이션에 Artifacts 미리보기가 포함되어 있다면 분할 막대 자체의 마우스 이벤트만 수신하기보다 이 모듈을 우선 재사용해야 합니다.
키보드 사용자를 위한 완전한 탐색 유지
useClaudeRovingFocus는 1차원 또는 2차원 방향키 탐색, Home 및 End 경계 이동, RTL 미러링을 지원합니다. 모델 그리드, 첨부 파일 목록 또는 도구 카드 배열을 구축할 때는 올바른 ARIA 의미와 가시적 포커스 상태도 함께 유지해야 합니다.
모델 속도 제한 및 서비스 오류 처리
useRateLimitBackoff는 429 및 503 응답을 대상으로 절단 지수 백오프, 지터 주입, 세 번의 자동 회로 차단 복구 기능을 제공합니다. 모델 요청 계층에 적합하지만, 재시도할 시점, 오류를 표시할 시점, 사용자의 수동 복구를 허용할 시점은 애플리케이션이 자체 API 응답 구조에 따라 결정해야 합니다.
기술 매뉴얼로 심층 학습하기
컴포넌트 소스 코드 외에도 저장소에는 3,000줄이 넘는 디자인 시스템 기술 매뉴얼이 제공됩니다. 다음 순서로 읽는 것을 권장합니다.
- 먼저 디자인 철학, Surface 색상 단계, 모서리 반경 매트릭스 및 헤어라인 테두리 규칙을 읽습니다.
- 그다음 버튼, 세그먼트 컨트롤, 상태 표시기 및 확인 대화 상자를 학습합니다.
- 이후 세션 입력, CJK 가드, 모델 전환 및 MCP 상태 머신을 살펴봅니다.
- 복잡한 애니메이션이 필요할 때 스프링 매개변수, 환경광 및 스크롤 마스크를 확인합니다.
- 데스크톱, 미디어 도구 또는 협업 공간을 개발할 때는 해당 시스템 아키텍처 장을 읽습니다.
전체 매뉴얼은 docs/Claude Design System (CDS).md에 있습니다. 프로젝트의 역분석 작업은 REA를 기반으로 완료되었습니다.
AI Coding Agent와 협업하기
저장소에는 AGENTS.md, CLAUDE.md, .cursorrules 및 Copilot 지침 파일이 제공됩니다. Cursor, Claude Code, GitHub Copilot 등의 도구로 새 인터페이스를 생성할 때 Agent에게 저장소의 기존 토큰, 스프링 프리셋, 테두리 원칙 및 입력기 보호 규칙을 따르도록 요청할 수 있습니다.
예시 프롬프트: 이 저장소의 AGENTS.md 규정을 엄격히 준수하고 CDS 테라코타 디자인 토큰과 ClaudeMotionPresets 스프링 프리셋을 사용해 현재 컴포넌트를 구축해 주세요.
요약
open-claude-ui는 AI 클라이언트의 시각적 토큰, 세션 컨트롤, 애니메이션 물리, 멀티미디어 상호작용 및 데스크톱 아키텍처를 재사용 가능한 모듈로 정리합니다. 가장 안정적인 도입 방법은 먼저 오프라인 Storybook으로 결과를 확인한 다음 테마 CSS와 Tailwind 확장을 도입하고, 마지막으로 채팅 입력창, 모델 전환기 및 스크롤 컨테이너 같은 핵심 컴포넌트부터 조합하는 것입니다. 스트리밍 출력, CJK 입력, iframe 드래그 및 키보드 탐색과 같은 복잡한 상황에서는 표면적인 스타일만 복사하기보다 저장소에 이미 있는 Hooks와 상태 머신을 최대한 재사용해야 합니다.