@godpeople/gds

갓피플 콘텐츠 플랫폼 통합 디자인 시스템. user, tong 등 사내 프로젝트가 공통으로 쓰는 색상·타이포그래피 토큰, CSS, Official GDS React 컴포넌트 42개를 배포합니다.

Implementation Source of Truth는 이 저장소가 아닙니다. 실제 컴포넌트 개발은 user 레포의 src/components/v3/gds에서 이루어지고, 이 저장소는 그 원본을 빌드해서 배포용 사본으로 전달만 합니다. 컴포넌트를 여기(dist/)에서 직접 고치지 마세요 — 다음 빌드 때 덮어써집니다.

설치

npm 레지스트리 정식 게시 여부가 아직 확정되지 않아, git 저장소 + 버전 태그 기준으로 설치합니다:

npm install github:jiyoun0712/godpeople-design-system#v3.1.0

Consumer의 package.json에서도 정식 버전 태그를 고정합니다:

{
  "dependencies": {
    "@godpeople/gds": "github:jiyoun0712/godpeople-design-system#v3.1.0"
  }
}

GDS React 컴포넌트 사용

이 패키지는 src/components/v3/gds의 Official Component Inventory에 등록된 42개 컴포넌트를 표준 ESM JS로 빌드해서 dist/components/에 포함합니다. react/react-dom은 패키지에 번들되지 않으므로, Consumer 프로젝트에 이미 설치된 React(17 이상)를 그대로 씁니다.

개별 import (기본 권장)

import GDSButton from '@godpeople/gds/GDSButton';
import GDSCard from '@godpeople/gds/GDSCard';

컴포넌트 하나당 import 하나 — tree-shaking이 번들러 설정에 좌우되지 않고 항상 명확하게 보장됩니다. AI 코딩 에이전트가 "이 import = 이 컴포넌트"로 1:1 대응을 파악하기도 쉽습니다.

Barrel import (편의용, named export)

import { GDSButton, GDSCard } from '@godpeople/gds';

편의를 위해 함께 지원하지만, 번들러의 tree-shaking 설정이 느슨하면 안 쓰는 컴포넌트까지 번들에 딸려 들어갈 수 있습니다 — 가능하면 개별 import를 우선 쓰세요.

컴포넌트를 복사하거나 직접 수정하지 마세요

node_modules/@godpeople/gds/dist/components/의 파일을 프로젝트 안으로 복사해서 쓰거나 그 자리에서 직접 고치지 마세요. 필요한 변경은 GDS Owner(user 레포의 src/components/v3/gds)에 먼저 반영되고, 그 결과가 다음 버전으로 이 패키지에 배포됩니다. Consumer 프로젝트에서 GDS를 "포크"하면 원본과 조용히 갈라져서(props/동작이 달라지는 등) 나중에 되돌리기 어려워집니다.

Tailwind / 토큰 설정 (React 컴포넌트를 쓰려면 필수)

GDS 컴포넌트는 tw- 접두사 Tailwind 유틸리티 클래스를 하드코딩하고 있습니다. tailwind.config.js에 preset을 추가합니다:

module.exports = {
  prefix: 'tw-', // 반드시 유지 — GDS 컴포넌트가 tw- 접두사로 하드코딩되어 있음
  darkMode: 'class',
  presets: [require('@godpeople/gds/tailwind-preset')],
  content: ['./src/**/*.{js,jsx,ts,tsx}', './node_modules/@godpeople/gds/dist/**/*.js'],
};

앱 진입점에서 CSS 변수 정의를 불러옵니다(preset의 var(--color-*) 참조가 실제 값을 가지려면 필수):

import '@godpeople/gds/dist/color-vars.css';

다크모드는 document.documentElement.classList.toggle('dark', isDark) 방식으로 켭니다(html.dark).

Tailwind 없는 프로젝트 / 순수 HTML·CSS (React 컴포넌트 미사용)

<link rel="stylesheet" href="node_modules/@godpeople/gds/dist/tokens.css">
<link rel="stylesheet" href="node_modules/@godpeople/gds/dist/gds.css">

tokens.css가 반드시 gds.css보다 먼저 로드되어야 합니다. .gds-button, .gds-badge 같은 클래스로 컴포넌트 스타일을 직접 조합해서 씁니다. 자세한 클래스 목록은 gds.css 주석과 DESIGN_SYSTEM.md를 참고하세요.

AI 바이브코딩 지원

이 패키지에는 AI 코딩 어시스턴트가 참고할 문서 2개가 포함되어 있습니다:

• DESIGN_SYSTEM.md — 토큰/컴포넌트 사양 (사람이 읽는 레퍼런스)
• gds-ai-component-mapping.md — Official Component Inventory + AI가 마크업을 GDS 컴포넌트로 치환할 때 따르는 탐지·변환 규칙(Contract 원본). 개별 컴포넌트를 새로 만들기 전에 이 파일의 Inventory부터 확인하세요.

설치하면 node_modules/@godpeople/gds/에 두 파일이 함께 설치됩니다. 프로젝트의 CLAUDE.md(또는 다른 AI 컨텍스트 파일)에 아래처럼 한 줄만 추가하면 됩니다:

GDS 컴포넌트/토큰 규칙은 node_modules/@godpeople/gds/gds-ai-component-mapping.md 를 따른다.

Consumer 프로젝트 AI 규칙 템플릿

신규 GDS Consumer 프로젝트를 시작할 때는 templates/consumer/AGENTS.md.template / templates/consumer/CLAUDE.md.template을 그 프로젝트의 AGENTS.md / CLAUDE.md로 복사해서 씁니다. 복사 후 {{PROJECT_NAME}}, {{GDS_PACKAGE_NAME}}, {{GDS_CONTRACT_PATH}}, {{GDS_VERSION_SOURCE}}, {{GDS_OWNER_PROJECT}}, {{DOMAIN_COMPONENT_PATH}} placeholder를 프로젝트 환경에 맞게 채웁니다. 컴포넌트별 상세 prop/variant/token 기준은 이 템플릿에 옮겨 적지 않고, 설치된 패키지의 gds-ai-component-mapping.md를 그대로 원본으로 참조합니다.

토큰 체계 안내 (중요 — 두 시스템이 공존합니다)

이 패키지 안에는 이름이 다른 두 개의 색상 변수 체계가 있습니다. 섞어 쓰지 마세요.

| | dist/color-vars.css | dist/tokens.css | | --- | --- | --- | | 변수 이름 | --color-primary, --color-text-primary 등 | --sys-action-primary, --sys-text-primary 등 | | 용도 | tailwind-preset.js/GDS 컴포넌트가 참조하는 실제 값 | Tailwind 없이 gds.css를 쓸 때의 Primitive→Semantic 토큰 | | 언제 쓰나 | Tailwind 프로젝트, GDS React 컴포넌트 사용 시 | 순수 CSS 프로젝트(컴포넌트 미사용) |

두 파일의 실제 색상 값은 거의 동일하지만, 변수 이름 체계가 다르므로 한 프로젝트 안에서 두 방식을 혼용하면 안 됩니다.

빌드 방식 (Owner 전용)

dist/components/*.js와 dist/index.js는 사람이 직접 작성/수정하지 않습니다. npm run build:components(scripts/build-components.mjs)가 user 레포의 src/components/v3/gds(Official Component Inventory 기준)를 읽어 JSX-in-.js 소스를 esbuild로 표준 ESM JS로 변환해서 생성합니다. dist/index.js도 같은 스크립트가 Inventory 목록을 기준으로 자동 생성합니다. 컴포넌트를 추가/수정하려면 이 저장소가 아니라 user 레포의 GDS 원본을 먼저 고치고, 여기서는 빌드만 다시 돌립니다.

버전 관리

• Semantic Versioning을 따릅니다. 토큰 이름 변경/삭제, 컴포넌트 prop 변경은 major 버전으로 취급합니다.
• 변경 이력은 DESIGN_SYSTEM.md 하단 "변경 이력" 표를 참고하세요.

유지보수

user, 디자이너가 공동으로 관리합니다. 변경 시 src/components/v3/gds(원본) → scripts/build-components.mjs 빌드 → dist/* / tailwind-preset.js / DESIGN_SYSTEM.md / gds-ai-component-mapping.md를 함께 갱신해야 합니다 — 코드와 문서가 따로 노는 것을 방지하기 위함입니다.