Releases: kh1012/instant-elements
Release list
v1.0.0 — instant-elements
A UI harness for coding agents. Describe what you need, an agent builds it, the gallery shows it, and every change is recorded.
npm install -D instant-elements
npx ie init && npx ie skills install
npx ie galleryThe loop
"a stat card for the dashboard header"
↓ the agent looks for something reusable first
↓ if nothing fits: three files + a registry entry
you look at it in the gallery
↓ copy the modify prompt → the agent edits it
it gets recorded (who · when · what · which commit)
↓
assemble pages from what you've built → point at what to fix
↓
chain pages into a click-through demo
Why
Design systems drift for a boring reason: when finding the existing button is harder than writing a new one, people write a new one. This makes reuse the path of least resistance — the agent searches the registry before writing anything.
What's in it
- Registry — one entry per component, deterministic index (regenerating never creates a diff), append-only history including reuse recommendations
- Gallery — library, detail with live preview, integration and modify prompts, history timeline. Self-contained: a broken component can't break the tool you use to look at broken components
- Semantic tokens — brand-neutral defaults, swappable for your own
- Pages — assembled as data, version-guarded saves, point-and-comment review that becomes one executable prompt
- Flows — chain pages into a click-through demo, pinned to the page version at the time you added it
- Gates —
ie element validate(color literals, off-scale values, unknown tokens, animation contract) andie element schema --checkfor CI - Restore — roll a component back to a past commit
- Skills —
element-createandpage-create, with one canonical guide thatnpm updatekeeps current
Design notes
Everything is config-driven. The CLI, gallery, and skills read ie config --json rather than hardcoding paths — that's what lets the same skill instructions work in any project layout.
Animation support is declared, never inferred. Guessing from DOM selectors breaks silently the moment markup changes or something renders through a portal.
Saves are version-guarded. Hand back the version you read as --base, or the save is rejected rather than silently overwriting someone else's edit.
199 tests. Working example in examples/vite-react.
Docs
v0.3.0 — Phase 3: 검증한다 · 되돌린다 · 시연한다
루프를 신뢰할 수 있게 만드는 네 가지가 들어갔습니다.
props 스키마 자동 추출
npx ie element schema --check # 드리프트 시 종료코드 1이 스키마는 문서용이 아닙니다 — 페이지 조립이 이걸 읽어 실 컴포넌트에 값을 넘깁니다. 코드와 어긋나면 페이지가 없는 prop 을 넘기거나 있는 prop 을 못 채웁니다.
TypeScript 컴파일러 API 대신 구문 파싱을 씁니다. 컴파일러를 쓰면 CLI 가 소비 프로젝트의 tsconfig·경로 별칭·타입 의존을 전부 해석할 수 있어야 하고 7MB 런타임 의존이 붙습니다. 필요한 건 한 파일 안 Props 인터페이스의 표면뿐입니다.
검증 게이트
npx ie element validate --animation-strict색 리터럴 · Tailwind 팔레트 클래스 · 스케일 밖 임의값 · 알 수 없는 st-* 토큰(오타는 색이 안 나오는 것으로 끝나 발견이 늦습니다) · 엔트리↔코드 쌍 · 데모 존재.
애니메이션 계약 — "이 컴포넌트에 애니메이션 붙여줘"에 답하려면 어떤 효과를 어디에 얹을 수 있는지 알아야 합니다. DOM 셀렉터로 추측하면 포털이나 마크업 변경에 조용히 깨지므로, 레지스트리에 선언된 것만 인정합니다. part/list/text 는 증거를 요구하고, behavior 는 reducedMotion 을 반드시 정해야 하며, 자유 수치 파라미터는 막습니다.
git SHA 복원
npx ie element restore stat-card --to <sha>히스토리에 sha 를 남긴 이유가 여기 있습니다. revert 가 아니라 checkout <sha> -- <paths> 를 쓰는데, 같은 커밋에 다른 컴포넌트가 섞여 있을 수 있기 때문입니다. 작업 트리가 더러우면 멈추고, 결과를 새 커밋으로 남겨 복원 자체도 되돌릴 수 있습니다.
흐름 시연
npx ie flow create "온보딩"
npx ie flow add 온보딩 --screen 대시보드
npx ie flow link 온보딩 --from "대시보드:P-chart" --to 상세
npx ie flow check 온보딩연결은 노드 통짜이거나 컴포넌트가 선언한 type:"action" 콜백에 붙습니다. value 까지 구분하므로 탭 3개를 각각 다른 화면으로 보낼 수 있습니다 — DOM 셀렉터와 달리 포털·라벨 보간에 영향받지 않는, 컴포넌트의 공개 API 이기 때문입니다.
편입 시점 버전을 박제합니다. 페이지를 리파인해도 진행 중인 시연이 흔들리지 않습니다. flow check 는 사라진 노드(리파인 중 id 를 바꾸면 조용히 끊깁니다)와 닿지 않는 화면을 미리 잡습니다.
테스트 199건.
다음
영문 문서 · 예제 앱 · 1.0.0 — Phase 4.
v0.2.0 — Phase 2: 조립한다 · 짚는다 · 넘긴다
컴포넌트를 쌓았으면 그걸로 화면을 조립할 차례입니다.
페이지는 코드가 아니라 데이터
에이전트가 말로 조립하고, 사람이 리뷰하고, 되돌리는 일이 전부 한 JSON 위에서 일어납니다.
npx ie page create "대시보드"
# 에이전트에게: "상단에 GNB, 본문에 지표 카드 3개랑 추이 차트 자리"
npx ie gallery # → /pages/대시보드리뷰가 편집기를 배우지 않아도 됩니다
미리보기에서 고칠 자리를 클릭하고 의견을 남기면, 모아서 하나의 실행 가능한 프롬프트가 됩니다. 그 프롬프트에는 대상 페이지·현재 구조·노드 트리 경로·동시성 안전 저장 절차가 이미 실려 있습니다.
이번에 들어간 것
- 낙관적 동시성 — 읽은 버전을
--base로 돌려주지 않으면 저장을 거부합니다(종료코드 4). 통째로 덮어쓰게 두면 리뷰어의 손편집이나 다른 에이전트의 리파인이 조용히 사라집니다. - 버전 스냅샷 — 저장마다 남습니다. 흐름 시연이 "편입 시점의 화면"을 박제할 자리입니다(Phase 3).
- 구조
_-props —fill은 부모 방향에 따라 뜻이 달라집니다. Row 자식이면flex:1, 세로 흐름이면width:100%, Grid 자식이면 트랙에 맡깁니다. 부모를 모른 채flex:1을 내면 Stack 안에서 세로로 늘어납니다. - 랜드마크 역할 — 최상위 컨테이너의
_role이 실제<header>·<nav>·<main>으로 방출됩니다. 중복되면 첫 노드만 유지합니다. - 3가지 미리보기 모드 — 최소(뼈대) · 요약(별칭·역할·크기) · 라이브(실 컴포넌트에 페이지 props 반영)
- 고정 크기 캔버스 — 1:1 로 그립니다. 축소하면 포털로 빠져나가는 모달·팝오버가 스케일 밖에 그려져 어긋납니다.
page-create스킬
명령
ie page list | get | create | set | history | versions | catalog
테스트 162건.
다음
흐름 시연 · git SHA 복원 · 애니메이션 계약 · props 스키마 추출 — Phase 3.
v0.1.0 — Phase 1: 만든다 · 본다 · 기록된다
maxflow의 ui + ui-harness를 어떤 React + Tailwind v4 프로젝트에서도 쓸 수 있게 일반화한 첫 릴리스입니다.
핵심 루프가 관통합니다
npx ie init # 설정·디렉토리·유틸 스캐폴드
npx ie skills install # 코딩 에이전트에 스킬 설치
npx ie gallery # http://127.0.0.1:9221이제 에이전트에게 "대시보드에 쓸 지표 카드 만들어줘" 라고 말하면 — 재사용을 먼저 찾고, 없으면 만들고, 갤러리에 뜨고, 이력이 남습니다.
무엇이 일반화됐나
원본은 모노레포 경로가 코드 전반에 문자열로 박혀 있어 이식할 수 없었습니다. 그 방향을 뒤집었습니다.
- 가상 모듈 — 갤러리 소스가 상대경로
import.meta.glob으로 패키지 경계를 넘던 자리를, 해석된 설정을 읽어 모듈을 생성하는 Vite 플러그인으로 교체했습니다. 소비자 디렉토리 구조가 무엇이든 갤러리 코드는 바뀌지 않습니다. - 설정 하나가 모든 경로의 진실 — CLI도 갤러리도 스킬도
ie config --json이 내놓는 절대경로만 봅니다. 스킬 GUIDE에 경로가 한 줄도 없습니다. - 갤러리가 소비자 라이브러리에 의존하지 않음 — 도구가 자기 힘으로 떠야 "컴포넌트가 깨져서 컴포넌트를 못 보는" 순환이 안 생깁니다.
- 스킬 정본은 하나 — 설치되는 건 스텁이고, 절차는
ie guide로 매번 새로 읽습니다.npm update가 곧 지침 갱신입니다.
포함
- 시맨틱 토큰(
st-*) — 브랜드 중립 기본값 + 프로젝트 토큰으로 교체 가능 - 레지스트리 — 결정적 인덱스(재생성만으로 diff가 나지 않음), append-only 히스토리
- 갤러리 — 라이브러리(검색·필터·정렬) · 상세(프리뷰·사용예제·히스토리 타임라인) · 통합/수정 프롬프트 복사
element-create스킬- 테스트 118건
제외
승격·머지 거버넌스(component-curate / component-apply)는 의도적으로 뺐습니다. 만든다 · 수정한다 · 기록된다만 남깁니다.
다음
페이지 조립(page-create)과 노드 지목 피드백 — Phase 2.