@spectrabrain/eds 0.0.1

package/AI.md

@@ -0,0 +1,48 @@
+# EVA Design System — 소비처 AI 가이드
+
+이 문서는 `@spectrabrain/eds`를 사용하는 제품 저장소의 AI와 자동화 도구를 위한 공개 안내입니다. 설치된 패키지 버전의 API를 최종 기준으로 사용합니다.
+
+## 현재 공개 범위
+
+- React 웹용 semantic color·typography token과 token runtime API를 제공합니다.
+- `Button` React 컴포넌트를 제공합니다.
+- `@spectrabrain/eds/styles.css`, `@spectrabrain/eds/tokens.css`, `@spectrabrain/eds/fonts.css`를 제공합니다.
+- `styles.css`는 Pretendard Variable font, semantic CSS custom property, Button CSS를 함께 불러옵니다. `fonts.css`는 font만 불러옵니다.
+
+문서에 없는 API, variant, loading 동작은 추측해서 구현하지 않습니다. 공개되지 않은 토큰 원본을 직접 import하지 않습니다. dark theme와 Tailwind utility API도 지원하지 않습니다.
+
+## 토큰 사용
+
+~~~ts
+import "@spectrabrain/eds/styles.css";
+import { cssVar, type SemanticTokenName } from "@spectrabrain/eds/tokens";
+
+const token: SemanticTokenName = "color-fg-brand";
+const color = cssVar(token); // var(--eds-color-fg-brand)
+~~~
+
+- 색상에는 `SemanticTokenName`, `cssVar()`, 또는 `--eds-*` CSS variable만 사용합니다.
+- text style은 같은 style의 `fontFamily`, `fontWeight`, `fontSize`, `lineHeight`, `letterSpacing` token을 함께 적용합니다.
+- `styles.css`를 import하면 font와 token CSS를 함께 불러옵니다. `tokens.css`만 사용하는 경우 text style에 `fonts.css`를 추가합니다.
+- 문서에 없는 deep import, raw 색상값, 임의 CSS variable은 사용하지 않습니다.
+- 역할에 맞는 semantic token이 없으면 임의 값을 만들지 말고 디자인 시스템 담당자에게 요청합니다.
+
+## 컴포넌트가 추가된 뒤
+
+각 컴포넌트의 공식 API와 설치된 패키지 버전을 먼저 확인합니다. 현재 제공하는 Button은 다음 규칙을 따릅니다.
+
+- `size`는 `xs`, `sm`, `md` 중 하나를 필수로 지정합니다.
+- `role`은 `brand`, `neutral`, `critical` 중 하나를 필수로 지정하며 시각적 역할로만 사용합니다.
+- `brand`는 `solid`, `outline`, `neutral`은 `solid`, `weak`, `outline`, `ghost`, `link`, `critical`은 `weak`만 허용합니다.
+- native button branch에서는 `type`을 필수로 지정합니다. `neutral/link`는 `href`가 필수인 `<a>`입니다.
+- children과 아이콘 슬롯 조합으로 layout을 결정합니다. icon-only는 비어 있지 않은 `aria-label`이 필수입니다.
+- disabled link는 href를 제거하고 키보드 순서에서 제외합니다. `role="link"`를 임의로 추가하지 않습니다.
+- `loading`은 처리 중임을 나타냅니다. 라벨과 공간은 유지되고 내부 progress circle이 표시되며, native button은 비활성화되고 link는 href가 제거됩니다. loading 중에는 `aria-busy="true"`가 제공되며 `prefers-reduced-motion: reduce` 환경에서는 애니메이션이 정지합니다.
+- `iconName`, `startIconName`, `endIconName`은 `ButtonIconName` 자동완성을 제공하는 lucide PascalCase 이름입니다. 이름으로 지정한 아이콘은 `lucide-react`의 기본 시각 설정을 사용하며 Button이 아이콘 영역 크기를 조정합니다. custom 아이콘은 단일 `ReactElement`만 허용하며 같은 슬롯의 이름 prop과 함께 지정하지 않습니다.
+- Button에는 typography prop이 없습니다. label은 `xs`에서 `typography.semantic.body3`, `sm`·`md`에서 `typography.semantic.title3`을 사용하며, 공개 text style semantic token은 Storybook 검토용 preset과 컴포넌트 내부 mapping에서 사용합니다. 소비처는 raw typography 값이나 component token override로 Button 글꼴을 덮어쓰지 않습니다.
+- `className`, native `aria-*`, `data-*`만 추가하며 `style`로 시각 정책을 우회하지 않습니다.
+
+- 제공되는 EDS 컴포넌트를 유사한 자체 구현보다 우선 사용합니다.
+- typed prop으로 제공하지 않은 색상, 상태, variant를 `className`이나 inline style로 우회하지 않습니다.
+- native semantics, accessible name, keyboard interaction을 임의로 변경하지 않습니다.
+- 컴포넌트 context와 manifest의 사용 목적·금지 사례를 따릅니다.

package/NOTICE

@@ -0,0 +1,16 @@
+EVA Design System third-party notices
+
+This package is UNLICENSED except for the third-party asset identified below.
+
+Pretendard Variable v1.3.9
+Copyright (c) 2021, Kil Hyung-jin (https://github.com/orioncactus/pretendard),
+with Reserved Font Name Pretendard.
+
+The unmodified WOFF2 file is distributed with this package under the SIL Open Font License, Version 1.1. The complete license text is included at dist/fonts/Pretendard-OFL-1.1.txt.
+
+Upstream source:
+https://github.com/orioncactus/pretendard/releases/tag/v1.3.9
+
+Bundled file:
+dist/fonts/PretendardVariable.woff2
+SHA-256: 9599f12fd42fc0bce1cd50b47a0c022e108d7aa64dd0d1bb0ed44f3282d900b4

package/README.md

@@ -0,0 +1,94 @@
+# EVA Design System
+
+EVA 서비스의 일관된 UI/UX를 위한 React 웹 디자인 시스템입니다. 공개 npm 패키지는 `@spectrabrain/eds`입니다.
+
+## 설치
+
+~~~sh
+npm install @spectrabrain/eds
+~~~
+
+## 현재 제공 범위
+
+- 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` 컴포넌트를 제공합니다.
+
+## Button 사용
+
+`Button`은 size·시각적 role·role에 종속된 variant·native button type을 명시해 사용합니다. `role="neutral"`, `variant="link"` 조합만 `href`를 사용하며 `<a>`로 렌더링합니다.
+
+~~~tsx
+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`과 비어 있지 않은 `aria-label`을 함께 제공합니다. `style`과 component token override는 지원하지 않습니다. 전체 contract와 접근성 규칙은 설치된 버전의 `AI.md`를 확인합니다.
+
+lucide 아이콘은 PascalCase 이름을 `iconName`, `startIconName`, `endIconName`으로 지정합니다. `ButtonIconName`이 TypeScript 자동완성을 제공하며, 같은 슬롯에 custom ReactElement와 이름을 함께 지정하지 않습니다. 이름으로 지정한 아이콘은 `lucide-react`의 기본 시각 설정을 사용하고 Button이 아이콘 영역 크기를 조정합니다.
+
+처리 중인 버튼은 `loading`을 지정합니다. 라벨 공간을 유지한 2색 progress circle을 표시하고 상호작용을 차단하며, link는 href를 제거합니다. `prefers-reduced-motion: reduce` 환경에서는 애니메이션이 정지합니다.
+
+## 토큰 사용
+
+CSS를 한 번 import한 뒤 `cssVar()`와 `SemanticTokenName`을 사용합니다. 공개 token 이름은 `-`로 구분하며 복합어 안에서만 lower camelCase를 사용합니다.
+
+~~~ts
+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 색인 방식에 따라 달라질 수 있습니다.
+
+필요한 역할의 token이 없으면 임의 색상값을 추가하지 말고 디자인 시스템 담당자에게 요청합니다.
+
+## Text style 사용
+
+하나의 text style은 다섯 속성을 함께 적용합니다.
+
+~~~css
+.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`, Button 내부 CSS를 함께 import하며 Pretendard Variable font에 `font-display: swap`을 사용합니다. 이 파일이 애플리케이션의 `font-family`를 자동으로 지정하지는 않습니다. `tokens.css`만 import한 소비처가 text style을 사용할 때는 `fonts.css`를 추가합니다. font의 license와 저작권 고지는 패키지의 [NOTICE](./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` | Pretendard font와 semantic CSS custom property를 함께 불러옵니다. |
+| `@spectrabrain/eds/fonts.css` | Pretendard font만 불러옵니다. |
+| `@spectrabrain/eds/tokens.json` | 도구 연동용 semantic token manifest입니다. |
+| `@spectrabrain/eds/package.json` | 패키지 메타데이터입니다. |
+
+표에 명시한 경로만 지원합니다. 설치된 패키지 버전의 API를 기준으로 사용합니다.
+
+## 소비자 가이드
+
+AI와 자동화 도구를 위한 규칙은 [AI.md](AI.md)에서 확인합니다. React 컴포넌트가 추가되면 해당 컴포넌트의 공식 API와 사용 규칙을 먼저 확인합니다.
+
+## 라이선스
+
+이 패키지는 현재 `UNLICENSED`입니다. 번들 Pretendard font는 SIL Open Font License 1.1로 제공하며 세부 고지는 [NOTICE](./NOTICE)에서 확인합니다. 그 밖의 사용·재배포 권한은 EVA 디자인 시스템 담당자에게 문의합니다.