EVA Design System

EVA 서비스의 일관된 UI/UX를 위한 React 웹 디자인 시스템입니다. 공개 npm 패키지는 @spectrabrain/eds입니다.

설치

npm install @spectrabrain/eds

소비처 AI와 자동화 도구는 설치 후 QUICKSTART.md를 먼저 읽습니다. 4 KB 이하의 유일한 필수 문서이며, AI_CONTEXT.json의 조건에 해당할 때만 CONSUMER_AGENT.md 등 나머지 문서를 읽습니다. npm 10·11에서는 EDS postinstall이 소비처 package.json에 sync:eds·eds:doctor script를 등록하고, 의존성의 install script가 실행되지 않는 npm 12·pnpm·yarn berry·bun에서는 npx @spectrabrain/eds init이 같은 script를 등록한 뒤 패키지 매니저별 승인 절차를 기록하거나 안내합니다. 설치·업데이트 후 npm run sync:eds를 실행하면 Tailwind root CSS의 EDS import, Tailwind token alias, AGENTS.md managed block과 CLAUDE.md·GEMINI.md의 import 줄을 갱신하고, npm run eds:doctor가 동기화 상태와 EDS font import를 읽기 전용으로 점검합니다. Tailwind를 사용하지 않는 저장소에서는 sync가 Tailwind 배선을 건너뛰고 AGENTS.md만 갱신합니다.

최초 설치와 동기화를 한 번에 실행하려면 npm install @spectrabrain/eds && npm run sync:eds를 사용합니다.

@spectrabrain/eds/styles.css는 Pretendard font, semantic CSS custom property, html 기본 font family, Button CSS를 함께 불러옵니다. 개별 파일로 구성할 때는 @spectrabrain/eds/tokens.css, @spectrabrain/eds/components.css, @spectrabrain/eds/fonts.css를 함께 import하고 @spectrabrain/eds/base.css는 선택합니다. EDS text style은 fonts.css가 선언하는 font family Pretendard를 참조하므로, 앱이 Pretendard를 다른 경로로 불러오더라도 EDS fonts.css를 생략하지 않습니다.

현재 제공 범위

• foreground, background, stroke 역할의 semantic color token을 제공합니다.
• Display, Heading, Title, Body, Caption semantic text style을 제공합니다. 각 style은 font family, weight, size, line height, letter spacing token으로 구성합니다.
• styles.css에서 사용할 수 있는 Pretendard Variable v1.3.9 webfont를 제공합니다.
• 자동완성을 지원하는 TypeScript token API와 CSS custom property를 제공합니다.
• React Button 컴포넌트를 제공합니다. 이름으로 지정하는 lucide 아이콘은 승인된 allowlist로 제한합니다.
• 소비처 setup용 eds CLI(npx @spectrabrain/eds init, npm run sync:eds, npm run eds:doctor)를 제공합니다.

Button 사용

Button은 size·시각적 role·role에 종속된 variant·native button type을 명시해 사용합니다. role="neutral", variant="link" 조합만 href를 사용하며 <a>로 렌더링합니다.

import "@spectrabrain/eds/styles.css";
import { Button } from "@spectrabrain/eds";

export function SaveButton() {
  return (
    <Button size="md" role="brand" variant="solid" type="button">
      저장하기
    </Button>
  );
}

아이콘만 사용하는 경우 접근성 이름을 제공하려면 icon 또는 iconName과 aria-label을 함께 지정합니다. aria-label은 필수로 강제하지 않습니다. style과 임의 스타일 override는 지원하지 않습니다. 전체 contract와 접근성 규칙은 설치된 버전의 @spectrabrain/eds/components/Button/README.md와 @spectrabrain/eds/components/Button/spec.json(package root의 dist/components/Button/)을 확인합니다.

lucide 아이콘은 승인된 allowlist의 PascalCase 이름을 iconName, startIconName, endIconName으로 지정합니다. ButtonIconName은 이 allowlist와 같은 union이며 TypeScript 자동완성을 제공하고, 설치된 dist/components/Button/spec.json(@spectrabrain/eds/components/Button/spec.json)의 api.iconNames에서 같은 목록을 확인합니다. allowlist 밖 아이콘은 icon/startIcon/endIcon에 ReactElement로 전달합니다. 같은 아이콘이 두 화면 이상에서 반복되면 allowlist PR을 엽니다. 같은 슬롯에 custom ReactElement와 이름을 함께 지정하지 않으며, 이름으로 지정한 아이콘은 lucide-react의 기본 시각 설정을 사용하고 Button이 아이콘 영역 크기를 조정합니다.

처리 중인 버튼은 loading을 지정합니다. 라벨 공간을 유지한 2색 progress circle을 표시하고 상호작용을 차단하며, link는 href를 제거합니다. prefers-reduced-motion: reduce 환경에서는 애니메이션이 정지합니다.

Button API

Button은 TypeScript 타입으로 허용된 role·variant 조합과 native element branch를 제한합니다. 필수 props를 생략하거나 허용되지 않은 조합을 지정하면 TypeScript 자동완성 단계에서 오류를 확인할 수 있습니다.

필수 props

| prop | 타입 | 규칙 | | --- | --- | --- | | size | "xs" \| "sm" \| "md" | 사용 공간과 행동의 중요도에 맞춰 선택합니다. 필수입니다. | | role | "brand" \| "neutral" \| "critical" | 액션의 의미를 나타내는 시각적 역할입니다. DOM의 ARIA role로 전달되지 않습니다. 필수입니다. | | variant | role별 아래 표 | 같은 role 안에서 시각적 위계를 결정합니다. 필수입니다. | | type | "button" \| "submit" \| "reset" | native <button> branch에서 필수입니다. neutral/link branch에서는 사용하지 않습니다. | | href | string | role="neutral", variant="link" branch에서 필수입니다. 이 branch는 <a>로 렌더링합니다. |

role·variant 조합

| role | 허용 variant | | --- | --- | | brand | solid, outline | | neutral | solid, weak, outline, ghost, link | | critical | weak |

선택 props와 슬롯

| prop | 타입·규칙 | | --- | --- | | children | ReactNode label입니다. 렌더링 가능한 내용이 하나 이상 필요하며 startIcon·endIcon과 조합할 수 있습니다. | | icon | icon-only용 단일 custom ReactElement입니다. children이나 다른 아이콘 슬롯과 함께 사용하지 않습니다. | | iconName | icon-only용 ButtonIconName lucide 이름입니다. allowlist에 있는 이름만 허용합니다. | | startIcon / endIcon | label 앞·뒤에 배치할 단일 custom ReactElement 슬롯입니다. | | startIconName / endIconName | label 앞·뒤에 배치할 ButtonIconName lucide 이름입니다. | | aria-label | 선택적인 accessible name입니다. icon-only의 접근성 이름을 제공할 때 지정하며, text label에서도 필요할 때 사용할 수 있습니다. | | disabled | 실행할 수 없는 상태입니다. native button은 disabled, link는 href 제거·aria-disabled="true"·tabIndex={-1}를 적용합니다. | | loading | 처리 중 상태입니다. label과 아이콘 공간을 유지하고 progress circle을 표시하며 상호작용을 차단합니다. aria-busy="true"를 적용합니다. | | className | 배치·컨테이너 보정용으로만 사용합니다. | | aria-* / data-* | native 속성으로 전달할 수 있습니다. | | ref | native button은 HTMLButtonElement, link는 HTMLAnchorElement를 전달합니다. |

style과 임의 스타일 override API는 제공하지 않습니다. lucide 이름과 custom ReactElement는 같은 슬롯에 함께 지정하지 않습니다. 이름으로 지정한 lucide 아이콘은 lucide-react 기본 시각 설정을 사용하며, Button은 아이콘 영역 크기만 조정합니다.

슬롯 조합에 따라 layout은 다음처럼 추론합니다.

| 조합 | layout | | --- | --- | | children만 지정합니다. | textOnly | | children과 startIcon 또는 startIconName을 지정합니다. | iconFirst | | children과 endIcon 또는 endIconName을 지정합니다. | iconLast | | children과 앞·뒤 아이콘을 모두 지정합니다. | iconBoth | | children 없이 icon 또는 iconName만 지정합니다. | iconOnly |

잘못된 슬롯 조합, 빈 label·icon 또는 제공된 빈 aria-label은 모든 환경에서 오류로 처리합니다. Button의 개요와 사용 맥락은 설치된 패키지의 @spectrabrain/eds/components/Button/README.md(package root의 dist/components/Button/README.md)를 기준으로 합니다.

토큰 사용

CSS를 한 번 import한 뒤 cssVar()와 SemanticTokenName을 사용합니다. 공개 token 이름은 -로 구분하며 복합어 안에서만 lower camelCase를 사용합니다.

import "@spectrabrain/eds/styles.css";
import { cssVar, type SemanticTokenName } from "@spectrabrain/eds/tokens";

const token: SemanticTokenName = "color-fg-brand-contrast";
const color = cssVar(token); // var(--eds-color-fg-brand-contrast)

SemanticTokenName을 사용하면 승인된 token 이름을 TypeScript 자동완성으로 선택할 수 있습니다. var(--eds-...)의 직접 자동완성은 에디터의 CSS import 색인 방식에 따라 달라질 수 있습니다.

@spectrabrain/eds/tokens의 타입은 exports의 types와 함께 typesVersions로도 dist/tokens.d.ts에 연결되어 있으므로, moduleResolution이 node(node10)인 소비처에서도 해석됩니다. bundler·node16에서는 exports가 우선합니다.

필요한 역할의 token이 없으면 임의 색상값을 추가하지 말고 디자인 시스템 담당자에게 요청합니다.

Tailwind CSS v4에서 token 사용

EDS는 Tailwind utility API를 패키지에 포함하지 않습니다. Tailwind CSS v4에서 공개 semantic token을 className으로 사용하려면 Tailwind CSS v4 token 설정 가이드를 확인합니다. 소비처의 npm run sync:eds가 tokens.json에서 src/styles/eds-tokens.css를 생성해 @import "tailwindcss"가 있는 Tailwind root CSS에 연결하며, text-eds-fg-*, bg-eds-bg-*, border-eds-stroke-*, eds-typography-* class를 사용합니다. 생성된 @theme inline에는 --font-sans: var(--eds-typography-body1-fontFamily);도 들어가므로 Tailwind의 기본 sans font가 Pretendard가 됩니다. root 후보가 둘 이상이면 EDS_TAILWIND_ROOT로 한 번 지정하며, sync가 그 경로를 소비처 package.json의 eds.tailwindRoot에 기록해 이후 doctor·hook이 재사용합니다. root가 없으면 sync는 Tailwind 배선을 건너뜁니다. 새 컴포넌트별 스타일은 index.css보다 className을 우선 작성합니다.

Text style 사용

하나의 text style은 다섯 속성을 함께 적용합니다.

.article {
  font-family: var(--eds-typography-body2-fontFamily);
  font-weight: var(--eds-typography-body2-fontWeight);
  font-size: var(--eds-typography-body2-fontSize);
  line-height: var(--eds-typography-body2-lineHeight);
  letter-spacing: var(--eds-typography-body2-letterSpacing);
}

styles.css는 fonts.css, tokens.css, base.css, components.css를 순서대로 import하며 Pretendard Variable font에 font-display: swap을 사용합니다. base.css는 :where(html)에 body1 font family를 지정하는 specificity 0 규칙 하나이므로 소비처의 html·body font-family 선언이 있으면 그 선언이 우선합니다. 개별 파일로 구성할 때는 tokens.css, components.css, fonts.css를 함께 import하고 base.css는 선택합니다. EDS text style은 fonts.css가 선언하는 family Pretendard를 참조하므로 다른 출처의 Pretendard로 fonts.css를 대체하지 않습니다. font의 license와 저작권 고지는 패키지의 NOTICE에서 확인합니다.

공개 경로

| 경로 | 용도 | | --- | --- | | @spectrabrain/eds | Button과 token runtime 진입점입니다. | | @spectrabrain/eds/tokens | semantic token runtime API와 타입입니다. | | @spectrabrain/eds/tokens.css | semantic CSS custom property입니다. | | @spectrabrain/eds/styles.css | fonts.css, tokens.css, base.css, components.css를 순서대로 불러옵니다. | | @spectrabrain/eds/components.css | Button CSS만 불러옵니다. font는 포함하지 않으며 tokens.css·fonts.css와 함께 사용합니다. | | @spectrabrain/eds/fonts.css | Pretendard font만 불러옵니다. EDS text style이 참조하는 family를 선언하므로 생략하지 않습니다. | | @spectrabrain/eds/base.css | :where(html)에 body1 font family를 지정합니다. styles.css에 포함되며 개별 구성에서는 선택입니다. | | @spectrabrain/eds/tokens.json | 도구 연동용 semantic token manifest입니다. | | @spectrabrain/eds/QUICKSTART.md | 소비처 AI의 유일한 필수 읽기 문서입니다. 4 KB 이하입니다. | | @spectrabrain/eds/CONSUMER_AGENT.md | 소비처 AI의 setup·sync·doctor 계약과 managed block 템플릿입니다. | | @spectrabrain/eds/AI.md | 소비처 AI의 공개 범위와 금지 사례입니다. | | @spectrabrain/eds/CHANGELOG.md | 버전별 변경 내용입니다. EDS 버전을 올린 뒤 읽습니다. | | @spectrabrain/eds/AI_CONTEXT.json | AI 문서 읽기 순서·우선순위·공개 manifest 경로를 제공합니다. | | @spectrabrain/eds/TOKEN_CONTEXT.md | semantic token의 역할과 화면 맥락입니다. | | @spectrabrain/eds/TAILWIND_V4.md | Tailwind CSS v4에서 공개 token을 연결하는 설치 가이드입니다. | | eds CLI (npx @spectrabrain/eds init) | 소비처 setup CLI입니다. init은 script 등록과 첫 동기화, npm run sync:eds는 동기화, npm run eds:doctor는 동기화 상태와 eds-* class 이름의 읽기 전용 점검을 실행합니다. 모듈로 import하지 않습니다. | | @spectrabrain/eds/components/Button/README.md | Button 개요·사용 맥락·공개 API 문서입니다. | | @spectrabrain/eds/components/Button/spec.json | Button 공개 API와 접근성 계약을 위한 manifest입니다. | | @spectrabrain/eds/llms.txt | AI 문서 읽기 순서입니다. | | @spectrabrain/eds/package.json | 패키지 메타데이터입니다. |

표에 명시한 경로만 지원합니다. 설치된 패키지 버전의 API를 기준으로 사용합니다.

소비자 가이드

AI와 자동화 도구를 위한 시작 규칙은 QUICKSTART.md, setup·sync·doctor 계약은 CONSUMER_AGENT.md, 공통 공개 범위는 AI.md, token 사용 맥락은 TOKEN_CONTEXT.md, 문서 읽기 순서는 llms.txt에서 확인합니다. React 컴포넌트를 사용하기 전에는 해당 컴포넌트의 공식 API와 사용 규칙을 먼저 확인합니다.

라이선스

이 패키지는 현재 UNLICENSED입니다. 번들 Pretendard font는 SIL Open Font License 1.1로 제공하며 세부 고지는 NOTICE에서 확인합니다. 그 밖의 사용·재배포 권한은 EVA 디자인 시스템 담당자에게 문의합니다.