Lucian UI

네 층위로 쌓는 React 컴포넌트 라이브러리입니다. 지금 128개. 공통 44 · 파생 16 · 조합 33 · 확장 35.

공통(common)   →  파생(derived)   →  조합(composed)  →  확장(extended)
Button            SplitButton        Toolbar            Composer
Input             SearchInput        FilterBar          ToolCallCard
Radio             SegmentedControl   Modal              PaymentSelector

• 공통 — 더 쪼갤 수 없는 것. 모든 제품에 있습니다.
• 파생 — 공통 하나를 바로 변형한 것. 새 개념이 아니라 같은 것의 다른 모습입니다.
• 조합 — 공통·파생 여럿을 배치해 알아볼 수 있는 단위가 된 것.
• 확장 — 도메인이 붙은 것. 조합 위에 그 분야의 사실이 얹힙니다.

외부 프로젝트에 설치하기

React 지원 선언은 ^18.2.0 || ^19.0.0입니다. 18.2.0·19.0.0·19.2.8의 외부 앱에서 Button·IconButton·Input·Glass·Card의 ref 전달, SearchInput 포커스 복귀와 Menu trigger를 검사했습니다. 전체 컴포넌트·SSR/RSC·외부 TypeScript 호환성을 모두 검증한 것은 아닙니다. npm run verify:react-refs로 tarball 설치 기반 검사를 다시 실행할 수 있습니다.

npm run verify:consumer는 외부 Vite 앱에서 TypeScript strict 검사와 production build 후 검색·표 편집·파일 제출·메뉴를 조작합니다. 지정한 세 React 버전과 두 폭·두 테마에서 통과했습니다. 범위와 알려진 한계는 I1 검증 기록에 있습니다. Vite consumer는 CSS import 타입을 위해 types: ["vite/client"]를 사용합니다. GitHub Actions는 브라우저 실행 없이 타입, Gallery/library build와 외부 Vite 앱 설치를 검사합니다. 위 React·화면 조작 검증은 과거 기록이며 현재 CI가 매번 수행하는 검사는 아닙니다. UI 검증은 지정한 Windows Chrome runner에서 별도로 진행합니다.

@lucian-seo/lucian-ui는 npmjs.com에 MIT 라이선스로 공개되어 있습니다. 현재 버전은 0.1.1이며 누구나 별도 token이나 private registry 설정 없이 설치할 수 있습니다. 기존 프로젝트에 GitHub/GitLab scope registry 설정이 있다면 제거하거나 npmjs.com으로 바꾸세요.

npm install @lucian-seo/lucian-ui

npm 계정 lucian-seo로 첫 등록을 완료했습니다. 이후 자동 배포 연결 절차는 공개 npm 배포 가이드를 참고하세요. GitHub 저장소의 공개 여부와 npm 패키지의 공개 여부는 별도로 설정합니다.

컴포넌트와 스타일을 가져옵니다. styles.css는 Pretendard Variable, 디자인 토큰, Grid, 모든 컴포넌트 스타일을 포함합니다. reset.css는 host 페이지 전체에 영향을 주므로 필요한 프로젝트만 가져옵니다.

import { Button, DataGrid } from "@lucian-seo/lucian-ui";
import { Tag } from "@lucian-seo/lucian-ui/derived";
import "@lucian-seo/lucian-ui/styles.css";
import "@lucian-seo/lucian-ui/reset.css"; // 선택

| subpath | 무엇 | |---|---| | @lucian-seo/lucian-ui | 128개 컴포넌트와 타입 | | /common /derived /composed /extended | 한 층위만 import할 때 사용합니다 | | /styles.css | Pretendard Variable, 디자인 토큰, Grid, 컴포넌트 스타일 | | /pretendard.css | 컴포넌트 없이 Pretendard Variable만 사용할 때 가져옵니다 | | /tokens.css | 컴포넌트 없이 디자인 토큰만 사용할 때 가져옵니다 | | /reset.css | 선택 사항인 reset |

package는 dist/lib의 JavaScript, 타입, CSS, 폰트와 README를 배포합니다. Gallery registry, DEMO.tsx, blocks, samples는 넣지 않습니다. JavaScript source map에는 컴포넌트 구현 소스가 포함되므로 npm 공개 배포 후 누구나 구현을 읽을 수 있습니다.

바꿀 수 있는 디자인 값

공통 디자인 값은 CSS custom property로 바꿉니다. theme, brand, density, radius variation도 같은 변수를 덮습니다.

.product-root {
  --accent: #7c3aed;
  --space-4: 18px;
  --radius-control: 6px;
  --duration-fast: 100ms;
}

컴포넌트가 공개한 변수도 해당 컴포넌트에서 바꿀 수 있습니다.

.product-root .button.button[data-size="md"] {
  --button-height: 44px;
  --button-pad: 20px;
}

모든 CSS 선언이 변수인 것은 아닙니다. display, position, state 배치처럼 컴포넌트 동작을 정하는 규칙은 컴포넌트가 소유합니다. 일부 고정 폭과 미세한 baseline 보정값도 아직 직접 값으로 남아 있습니다. 따라서 현재 package는 색상과 공통 scale을 바꿀 수 있지만, 모든 모양을 변수만으로 다시 설계하는 package라고 보장하지 않습니다.

--bp-*는 JavaScript와 문서가 읽는 기준값입니다. CSS media query는 custom property를 읽을 수 없어서 breakpoint를 바꾸려면 grid.css와 같은 폭을 사용하는 컴포넌트 CSS도 함께 빌드해야 합니다. 컴포넌트가 임의의 breakpoint를 추가하지 못하도록 계약 테스트가 검사합니다.

저장소에서 개발하기

npm install
npm run dev            # http://127.0.0.1:5173

| 경로 | 무엇 | |---|---| | / | 랜딩. 라이브러리 소개와 직접 조작하는 프리뷰 | | /?foundation | 디자인 토큰·그리드·글꼴과 설치 안내 | | /?samples | 기존 샘플북 카테고리 목록 | | /?pages | 기존 응용 페이지와 시각 예제 목록 | | /?assets | 에셋 목록 | | /?browse | 컴포넌트 브라우저. 왼쪽 목록 · 이름 거르기 · [ ] 앞뒤 · 너비와 테마 전환 | | /?c=<layer>/<name> | 데모 하나만. 스펙이 재고 스크린샷이 찍는 경로입니다 |

브라우저는 마지막 경로를 <iframe>으로 끼웁니다. 프리뷰에 뜨는 것이 스펙이 재는 것과 같은 문서라서, 탭 순서가 컴포넌트에서 시작하고 position: fixed가 프리뷰를 뜻하며 너비 버튼이 진짜 뷰포트 변경입니다.

베리에이션

컴포넌트를 포크하지 않고 프로덕션 셋을 여러 벌 뽑는 자리입니다. 루트(또는 어느 컨테이너든)에 속성 하나를 걸면 그 아래 전부가 따라옵니다.

<html data-theme="dark" data-brand="violet" data-density="compact">

| 스코프 | 값 | 덮는 것 | |---|---|---| | data-theme | dark | 모든 의미 역할 | | data-brand | violet · lime | 강조 역할 다섯 (--accent · -hover · -ink · -subtle · --on-accent) | | data-density | compact · spacious | --space-* 스케일 전체 |

기본값은 속성의 부재입니다. data-density="comfortable"은 없습니다. 기본은 :root이고, 그것을 다시 적으면 같은 숫자가 어긋날 자리를 하나 더 만드는 것입니다.

data-theme="light"는 예외이고, 하나뿐인 이유가 있습니다. 커스텀 속성은 상속되므로 어두운 페이지 안의 밝은 패널은 속성만으로는 밝아지지 않습니다. :root가 말한 값으로 돌아가라는 값이 CSS에 없어서, 밝은 테마를 블록으로 한 번 더 적어 두었습니다. 페이지 전체가 밝을 때는 여전히 아무것도 걸지 않습니다.

테마는 color-scheme도 함께 겁니다. 캐럿, 자동 완성 배경, 브라우저가 직접 그리는 달력은 토큰을 읽지 않고 이 속성만 읽습니다.

OS의 어두운 모드는 라이브러리가 따르지 않습니다. 스타일시트를 가져와도 화면의 겉모습은 바뀌지 않고, data-theme을 쓸 때만 바뀝니다. 언제 쓸지는 앱이 정합니다. OS 설정을 따르고 싶으면 한 줄이면 됩니다.

document.documentElement.dataset.theme =
  matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";

읽는 사람이 직접 고른 값이 있으면 그것을 먼저 쓰고 이 줄은 그 값이 없을 때만 씁니다. 이 저장소의 데모 사이트가 그렇게 동작합니다 (src/foundation/variation.ts).

컴포넌트는 셋 중 어느 것의 존재도 모릅니다. 밀도만 원시값을 고치는데, 간격에는 덮을 의미 층이 없기 때문입니다 — 근거는 docs/FOUNDATION.md 1-1에.

Table · ListRow · DataGrid의 density prop은 다른 것입니다. 이건 그 컴포넌트가 자기 행에 주는 자리이고, DOM에는 data-row-density로 나갑니다. 촘촘한 페이지 안의 촘촘한 표는 두 번 접히지 않고 겹쳐집니다.

styles.css를 가져오면 Pretendard Variable의 동적 subset과 OFL license도 package에서 함께 제공합니다. 화면에 쓰인 글자에 해당하는 subset만 브라우저가 내려받습니다. 채택자가 --font-sans를 다른 font family로 덮으면 Pretendard 파일은 내려받지 않습니다.

검증

npx tsc -b            # 타입
npm run build         # 갤러리 빌드 → dist/app
npm run build:lib     # 패키지 빌드 → dist/lib
npm run verify:package # tarball 생성 · 외부 Vite 앱 설치 · consumer build
# UI 검증은 C:\browser-runner\qa.js와 Windows Chrome으로 별도 진행

.github/workflows/verify.yml이 push와 PR에서 타입, 두 빌드, 외부 앱 package 설치를 확인합니다. publish.yml은 배포 활성화 후 release/tag를 검증하고 같은 tarball을 npmjs.com에 공개 배포합니다. 이전 GitHub Packages workflow는 .yml.disabled로 보관하며 실행하지 않습니다. Linux 브라우저는 설치하거나 실행하지 않습니다.

문서

| 파일 | 무엇 | |---|---| | AGENTS.md | 작업 규칙. 세션을 시작하면 먼저 읽으세요 | | PROJECT_STATE.md | 지금 상태와 정확한 다음 행동 | | docs/COMPONENTS.md | 81개 시점의 도출 기록 · 근거 · 층위마다 정해진 규칙 | | docs/FOUNDATION.md | 토큰 · 그리드 · 글꼴 | | docs/PRODUCTION-READINESS.md | 프로덕션까지 남은 것 — Mobbin 근거와 측정 | | docs/*.md (한글 3편) | 컴포넌트 목록이 나온 소스 문서 |

계약

tests/component-contract.spec.ts가 여덟 가지를 강제합니다. 문서가 아니라 테스트인 이유는 문서에만 있던 규칙이 지켜지지 않았기 때문입니다.

1. 인라인 스타일은 자기 custom property만 사용 — 페인트 선언과 style spread는 실패합니다.
2. 인라인 custom property는 자기 CSS가 읽어야 함 — 오타와 쓰이지 않는 이름을 막습니다.
3. 원시값 금지 — #2f6fed나 13px가 스타일시트에 있으면 실패합니다.
4. 중단점은 그리드의 중단점 — @media (max-width: var(--bp-sm))은 어느 엔진에서도 유효하지 않아서 중단점만은 토큰이 될 수 없습니다. 그 예외가 구멍이 되지 않게.
5. 루트는 두 클래스 — .text.text. 한 클래스는 .prose p에 집니다.
6. 데모 페이지가 컴포넌트 안으로 손을 뻗을 수 없습니다.
7. 제스처에는 포인터 없는 경로가 있어야 합니다.
8. DEMO.tsx가 있어야 합니다 — 갤러리는 glob으로 찾습니다.

그리고 이 여덟 개보다 먼저 도는 가드가 하나 있습니다: 계약이 무엇을 검사하는지 볼 수 있는가. 경로가 한 칸만 어긋나도 순회가 0개를 훑고 규칙 넷이 초록으로 통과하던 자리였습니다.

tests/package-surface.spec.ts는 공개 표면을 봅니다 — 배럴이 디스크와 일치하는지, styles.css가 128개를 다 담았는지, exports가 가리키는 경로가 실재하고 files가 그걸 싣는지, 그리고 두 빌드가 서로의 출력을 지우지 않는지. 배럴과 styles.css는 생성된 목록이고, 생성된 목록은 손으로 하나 추가하는 순간 거짓이 됩니다.

이전 작업선

archive/에 58개 컴포넌트와 그 문서·증적이 있습니다. 태그는 archive/v1-2026-08-24. 읽기용이고 현재 방향이 아닙니다.

라이선스

컴포넌트 코드는 MIT로 배포합니다. 포함된 Pretendard 폰트는 별도의 OFL 라이선스를 따릅니다.