Getting startedN
이 디자인 시스템은 제품 메인 컬러를 제외한 모든 기본 구성(색 · 글자 · 간격 · 컴포넌트 · 패턴)을 제공합니다. 역할에 맞는 탭을 골라 순서대로 따라 하면 됩니다.
어느 역할이든 각 컴포넌트 페이지가 사용법의 단일 출처입니다. Examples 로 실제 동작과 상태를, Props 표로 허용되는 변형을, 코드 보기로 HTML+CSS · React 코드를 확인합니다. 필요한 컴포넌트가 없으면 Contribution 절차로 제안합니다.
헤더의 Accent 선택으로 제품별 컬러를, 테마 버튼으로 다크 모드를 미리 볼 수 있고, 키보드 / 로 검색창을 엽니다.
- Figma 파일 열기JS Design System Figma 파일 ↗ — 페이지 구성(Home · Foundations · Components · Patterns · Resources)은 이 사이트와 같습니다. 어느 페이지에 무엇이 있는지는 Figma Library 표를 참고하세요.
- 내 디자인 파일에서 라이브러리 켜기작업할 파일을 열고 왼쪽 Assets 패널 → 책 모양(Libraries) 아이콘 → JS Design System 을 켭니다. 한 번 켜 두면 그 파일에서 계속 쓸 수 있습니다.
- 컴포넌트 넣기Assets 검색창에 이름(예: Button, Tag, Data Table)을 입력하고 캔버스로 끌어다 놓습니다. 넣은 것은 인스턴스라 원본은 바뀌지 않고, 원본이 갱신되면 따라서 갱신됩니다.
- 변형·상태 바꾸기인스턴스를 선택하면 오른쪽 패널에
variant·size·state드롭다운이 보입니다. 이름은 이 사이트 각 컴포넌트 페이지의 Props 표와 같아서, 개발자와 같은 말로 이야기할 수 있습니다. - 색·글자·그림자는 스타일만직접 색을 고르지 말고 채우기 → Variables 탭에서
bg/text/border/primary/status/severity/변수를 씁니다. 글자는 Text Style, 그림자는 Effect Style. 이렇게 해야 제품 컬러·다크 테마가 자동으로 맞춰집니다.
- 패키지 설치 + 앱 진입점 설정스타일시트를 한 번 import 하고, 토스트를 쓰려면 앱을
ToastProvider로 감쌉니다.applyAccent에 제품 메인 컬러 HEX 하나를 넣으면 나머지 색은 자동입니다.npm i @jiran/ds-react // main.tsx — 앱 진입점에서 한 번 import "@jiran/ds-react/style.css"; // 토큰 + 컴포넌트 CSS (사이트 크롬 제외) import { ToastProvider, applyAccent } from "@jiran/ds-react"; applyAccent("#1D4ED8"); // 제품 메인 컬러 → --accent-50~900 생성 createRoot(document.getElementById("root")!).render( <ToastProvider> <App /> </ToastProvider>, ); - 컴포넌트 가져다 쓰기변형은 HTML 클래스와 같은 이름의 prop 입니다. 전체 목록은 React Package › 컴포넌트 ↔ 클래스.
import { Button, TextField, Tag } from "@jiran/ds-react"; <TextField label="정책 이름" required /> <Tag tone="critical">Critical</Tag> <Button size="md" variant="primary">정책 저장</Button> - 테마·서체다크 테마는
html요소의data-theme로 정하고(또는setTheme("dark")), 앱 루트에.ds-root를 붙입니다.<!-- 다크 테마: html 요소에 지정. 없으면 시스템 설정을 따릅니다 --> <html data-theme="dark"> <!-- 앱 루트에 .ds-root 를 붙이면 서체·본문 색·배경 토큰이 적용됩니다 --> <div id="root" class="ds-root"></div>
- assets 폴더 복사저장소 ↗의
assets/style.css·assets/ds.js·assets/fonts/세 가지를 함께 프로젝트에 넣습니다.style.css가fonts/PretendardVariable.woff2를 상대 경로로 참조하므로 폴더 구조를 유지하고, 서버에.woff2MIME(font/woff2)이 등록돼 있어야 기본 서체로 보이지 않습니다. - HTML 에 연결스타일시트 한 줄, 동작 스크립트 한 줄입니다.
ds.js는 의존성 없는 순수 JS 로 드롭다운·탭·달력·표 정렬·토스트 등을 붙여 주며,defer로 싣고 나중에 DOM 에 넣은 마크업에는DS.init(요소)를 한 번 호출합니다. 다크 테마는body가 아니라html요소의data-theme="dark"로 정합니다.<!-- assets/ 폴더(style.css · ds.js · fonts/)를 프로젝트에 복사한 뒤 --> <link rel="stylesheet" href="assets/style.css"> <script src="assets/ds.js" defer></script> - 컴포넌트 페이지에서 복사예제 아래 코드 보기 → 복사. 전체 CSS 대신 일부만 쓰려면 같은 곳의 Component CSS 와 Design Token 의
:root토큰만 가져갑니다. 이벤트(ds:select·ds:tab등)와 API 는 React Package › assets/ds.js.<!-- 컴포넌트 페이지 HTML+CSS 탭에서 복사한 마크업을 그대로 붙입니다 --> <button class="btn md primary">정책 저장</button> <span class="tag critical">Critical</span> <script> DS.init(document.getElementById("dynamic-area")); // 나중에 DOM 에 넣은 마크업만 한 번 </script> - 제품 컬러 적용
--accent-*열 단계만 제품 메인 컬러로 바꾸면 나머지 토큰(무채색 · 상태색 · 간격 · 반경)은 그대로 씁니다. HEX 하나로 10단계를 만드는 함수는 Design Token › Accent 스케일 생성./* 제품 메인 컬러 하나로 생성한 10단계를 :root 에 덮어씁니다 (생성 함수는 Design Token › Accent 스케일 생성) */ :root{ --accent-50:#EFF2FA; --accent-100:#D8DFF3; --accent-200:#B1BFE7; --accent-300:#849CE1; --accent-400:#5A7CDC; --accent-500:#3661DA; --accent-600:#1D4ED8; --accent-700:#173DA8; --accent-800:#112D7D; --accent-900:#0B1E52; }
지원 환경
이 시스템은 데스크톱 웹(관리 콘솔) 만 공식 지원합니다. 아래 기준은 물리 해상도가 아니라 브라우저 viewport CSS px 기준이며, 새 화면은 이 표의 기준 프레임에서 시작합니다. 사이드 내비 폭·콘텐츠 최대 너비·컬럼 같은 레이아웃 값의 단일 출처는 Foundations › Grid 입니다.
| 지원 등급 | viewport | Figma · QA 기준 프레임 |
|---|---|---|
Compact desktop md | 1024–1279 | 1024×768 · 전환점 1280×800 |
Standard desktop lg (기준) | 1280–1919 | 1440×960 |
Wide desktop xl | 1920 이상 | 1920×1080 |
1023 이하(모바일 · 태블릿)는 미지원입니다. 데스크톱 콘솔을 축소해 제공하지 않으며, 터치 현장 업무가 확인되면 그때 별도 규칙과 업무 범위를 정의합니다. 미지원 범위를 "반응형 완료" 로 표기하지 않습니다.
1024 · 1280 · 1440 · 1920 네 폭을 매 릴리스에서 확인합니다color-mix() 사용). 100% 와 200% 확대에서 핵심 조치가 가능해야 합니다