NC AI Design System

NC AI Design System은 AI 에이전트가 React UI를 만들 때 사용할 수 있는 마크다운 우선 디자인 시스템 기반입니다. 원천 문서는 resources/design-system.md이며, 소비자 프로젝트에서는 완성된 스타일 컴포넌트를 받는 대신 Base UI primitive를 먼저 선택하고 이 문서의 디자인 기준을 즉석에서 적용합니다.

Base UI는 접근 가능한 React UI를 만들기 위한 unstyled 컴포넌트 라이브러리입니다. 이 프로젝트는 Base UI와 Base UI Quick start의 흐름을 전제로 @base-ui/react를 사용합니다.

디자인이 적용된 컴포넌트 미리보기

빠른 시작

사용자가 AI 에이전트에게 “이 저장소 README를 보고 디자인 시스템을 적용해”라고 요청했다면, 에이전트는 먼저 현재 사용 중인 도구에 맞는 <agent> 값을 선택해 setup을 실행합니다. 현재 사용중인 에이전트를 확실히 알 수 없다면 임의로 추측하여 설치하지 말고 사용자에게 어떤 에이전트를 쓰는지 확인해야 합니다.

npx @ncai/design-system-cli setup --agent <agent>
npm i @ncai/design-system @ncai/design-system-icons @base-ui/react
npx @ncai/design-system-cli doctor

<agent>에는 다음 중 하나를 사용합니다.

Cursor를 사용하면 cursor
VS Code 또는 GitHub Copilot을 사용하면 vscode
Claude Code를 사용하면 claude
OpenAI Codex CLI를 사용하면 codex
Windsurf를 사용하면 windsurf
JetBrains AI Assistant를 사용하면 jetbrains
그 외 도구는 manual

Windows PowerShell에서 npm.ps1 실행 정책 때문에 npm이 막히면 npm.cmd를 사용합니다.

npx @ncai/design-system-cli setup --agent <agent>
npm.cmd i @ncai/design-system @ncai/design-system-icons @base-ui/react
npx @ncai/design-system-cli doctor

설치 후 UI를 만들 때는 Base UI primitive를 먼저 선택하고, 이 저장소의 design-system.md 기준을 소비자 프로젝트의 스타일 방식에 맞게 적용합니다.

아키텍처

아래 그림은 소비자 프로젝트, AI 에이전트, npm 패키지, MCP 도구, Base UI 공식 문서, 관리자 배포 흐름이 어떻게 연결되는지 보여줍니다.

패키지 구성

@ncai/design-system
- design-system.md 원문과 섹션 검색 헬퍼를 배포합니다.
- 소비자 프로젝트나 에이전트는 이 패키지를 통해 NC AI 디자인 기준을 코드에서 직접 조회하고, 필요한 섹션만 찾아 UI 구현에 반영할 수 있습니다.
@ncai/design-system-icons
- NC AI SVG 아이콘 파일과 검색 가능한 메타데이터를 배포합니다.
- 소비자 프로젝트는 @ncai/design-system-icons/icons/<file>.svg export 경로로 SVG를 직접 가져오거나, icons, searchIcons, getIcon 헬퍼로 적절한 아이콘을 찾을 수 있습니다.
@ncai/design-system-skills
- AI 에이전트가 NC AI 디자인 시스템과 Base UI를 함께 사용하는 방법을 이해할 수 있도록 지침 문서를 배포합니다.
- 특정 도구에만 묶인 컴포넌트 구현체가 아니라, 에이전트가 Base UI primitive를 먼저 선택하고 디자인 시스템 문서를 적용하도록 안내하는 작업 기준을 제공합니다.
@ncai/design-system-mcp
- NC AI 디자인 시스템 검색, Base UI 공식 문서 조회, 구현 레시피 생성, UI 코드 검증을 위한 MCP 도구를 제공합니다.
- 에이전트는 MCP를 통해 design-system.md와 Base UI API 문서를 함께 확인하고, 임의 스타일이나 오래된 import 같은 문제를 검증할 수 있습니다.
@ncai/design-system-cli
- npx로 실행할 수 있는 설치, 에이전트 지침 생성, MCP 설정, 진단, 검증, 문서 조회 명령을 제공합니다.
- 소비자 프로젝트에서 setup, show, doctor, validate 명령을 사용해 디자인 시스템 적용 환경을 빠르게 구성하고 점검할 수 있습니다.

사용법

설치와 에이전트 설정

소비자 프로젝트에서는 먼저 사용할 에이전트를 선택해 지침 파일과 MCP 설정을 생성합니다. <agent>에는 빠른 시작에 있는 지원 목록 중 하나를 넣습니다.

npx @ncai/design-system-cli setup --agent <agent>
npm i @ncai/design-system @ncai/design-system-icons @base-ui/react

Windows PowerShell에서 실행 정책 때문에 npm.ps1이 막히는 환경이라면 npm 대신 npm.cmd를 사용합니다.

npx @ncai/design-system-cli setup --agent <agent>
npm.cmd i @ncai/design-system @ncai/design-system-icons @base-ui/react

setup 명령은 선택한 에이전트가 읽을 수 있는 지침 파일과 MCP 설정을 생성합니다. 자동 설정 형식이 안정적인 에이전트는 설정 파일을 직접 작성하고, 도구나 버전에 따라 설정 방식이 달라질 수 있는 에이전트는 .ncai 아래에 가져다 쓸 MCP JSON 스니펫을 생성합니다.

일반적인 사용자는 위 세 패키지만 소비자 프로젝트 의존성으로 설치하면 됩니다. npx 대신 로컬에 버전을 고정하고 싶거나 오프라인/사내 레지스트리 환경에서 반복 실행해야 한다면 CLI/MCP를 개발 의존성으로 추가합니다.

npm i -D @ncai/design-system-cli @ncai/design-system-mcp

@ncai/design-system-skills는 Cursor Skill 파일(.cursor/skills/ncai-design-system/SKILL.md)을 로컬에서 설치할 때만 필요합니다. Claude, Codex, VS Code/Copilot 등은 CLI가 각 에이전트용 지침 파일을 직접 생성하므로 이 패키지를 별도로 설치하지 않아도 됩니다.

npm i -D @ncai/design-system-skills

지원하는 에이전트는 다음과 같습니다.

cursor: .cursor/skills/ncai-design-system/SKILL.md와 .cursor/mcp.json을 생성합니다.
vscode: .github/copilot-instructions.md와 .vscode/mcp.json을 생성합니다.
claude: CLAUDE.md와 .mcp.json을 생성합니다.
codex: AGENTS.md와 .ncai/codex-mcp.json을 생성합니다.
windsurf: .windsurfrules와 .ncai/windsurf-mcp.json을 생성합니다.
jetbrains: .ncai/jetbrains-agent-instructions.md와 .ncai/jetbrains-mcp.json을 생성합니다.
manual: .ncai/agent-instructions.md와 .ncai/manual-mcp.json을 생성합니다.

예시는 다음과 같습니다.

npx @ncai/design-system-cli setup --agent claude
npx @ncai/design-system-cli setup --agent vscode

기존 프로젝트 업데이트

이미 소비자 프로젝트에 NC AI Design System을 설치했다면 새 버전 배포 후 의존성을 업데이트합니다.

npm update @ncai/design-system @ncai/design-system-icons @base-ui/react

CLI/MCP를 로컬 개발 의존성으로 고정해 둔 프로젝트라면 함께 업데이트합니다.

npm update @ncai/design-system-cli @ncai/design-system-mcp

@ncai/design-system-skills는 Cursor Skill 파일(.cursor/skills/ncai-design-system/SKILL.md)을 로컬에서 설치할 때만 필요합니다. Claude, Codex, VS Code/Copilot 등은 CLI가 각 에이전트용 지침 파일(CLAUDE.md, AGENTS.md, .github/copilot-instructions.md 등)을 직접 생성하므로 이 패키지를 별도로 설치하지 않아도 됩니다.

npm update @ncai/design-system-skills

업데이트 후 사용하는 에이전트 설정을 다시 생성해 최신 지침과 MCP 설정을 반영합니다.

npx @ncai/design-system-cli setup --agent <agent>
npx @ncai/design-system-cli doctor --agent <agent>

업데이트는 패키지의 design-system.md, 아이콘 메타데이터, CLI/MCP/Skill 지침을 최신화합니다. 기존 애플리케이션 UI 코드를 자동으로 마이그레이션하지는 않으므로, 이후 UI 작업이나 리팩터링 때 에이전트가 최신 문서를 기준으로 반영하도록 요청합니다.

디자인 시스템 문서 조회

show는 패키지에 포함된 design-system.md를 터미널에서 확인하는 명령입니다. --query를 넣으면 관련 섹션만 검색해서 보여주고, --query가 없으면 전체 문서를 출력합니다. 에이전트가 MCP를 사용할 수 없는 환경에서 디자인 기준을 빠르게 확인할 때 사용합니다.

npx @ncai/design-system-cli show --query buttons
npx @ncai/design-system-cli show --query typography

설치 상태 진단

doctor는 소비자 프로젝트에 필요한 의존성과 에이전트 설정 파일이 있는지 확인하는 진단 명령입니다. @ncai/design-system, @ncai/design-system-icons, @base-ui/react, 지원 에이전트별 지침 파일, MCP 설정 파일 또는 MCP JSON 스니펫의 존재 여부를 확인합니다.

npx @ncai/design-system-cli doctor

다른 위치를 프로젝트 루트로 검사하려면 --cwd를 사용합니다.

npx @ncai/design-system-cli doctor --cwd ./apps/web

UI 코드 검증

validate는 생성된 UI 코드가 기본 가드레일을 어기지 않았는지 확인합니다. 예를 들어 이전 Base UI 패키지명 사용, Base UI로 만들 수 있는 인터랙티브 UI를 직접 만든 흔적, 디자인 시스템 근거가 필요한 직접 색상값 등을 점검합니다.

npx @ncai/design-system-cli validate --file src/App.tsx

에이전트 작업 흐름

AI 에이전트가 UI를 만들거나 리뷰할 때는 다음 순서를 따릅니다.

design-system.md를 읽거나 MCP로 검색합니다.
인터랙티브 UI는 가장 가까운 Base UI primitive를 @base-ui/react에서 선택합니다.
필요한 경우 MCP의 search_base_ui_docs 또는 get_base_ui_component_doc으로 Base UI 공식 Markdown 문서를 확인합니다.
아이콘이 필요하면 MCP의 search_icons 또는 @ncai/design-system-icons 메타데이터로 기존 SVG를 먼저 찾습니다.
Base UI의 접근성 구조와 상태 속성을 유지합니다.
마크다운 문서의 typography, color, spacing, radius, elevation, interaction 기준을 소비자 프로젝트의 스타일 방식에 맞게 적용합니다.
MCP validate_ui_code 또는 CLI validate로 결과를 점검합니다.

MCP를 사용할 수 있다면 다음 도구를 우선 사용합니다.

get_design_system_overview: NC AI 디자인 시스템 섹션 목록을 확인합니다.
search_design_system: 요청과 관련된 디자인 시스템 섹션을 검색합니다.
get_design_system_section: 특정 디자인 시스템 섹션의 원문을 확인합니다.
list_icons, search_icons, get_icon: NC AI SVG 아이콘 목록, 검색, 개별 메타데이터를 확인합니다.
list_base_ui_docs: Base UI 공식 문서 인덱스를 확인합니다.
search_base_ui_docs: Base UI 공식 문서를 검색합니다.
get_base_ui_component_doc: Base UI 컴포넌트 API 문서를 확인합니다.
compose_base_ui_recipe: 요청에 맞는 Base UI 우선 구현 레시피를 생성합니다.
validate_ui_code: 생성된 코드의 기본 가드레일을 점검합니다.

테스트 시나리오 예시

회원가입 화면으로 검증하기

외부 AI 에이전트에게 이 프로젝트를 테스트하도록 요청할 때는 다음처럼 요청할 수 있습니다.

README를 읽고 NC AI Design System이 잘 반영되는지 확인하기 위해 React로 회원가입 화면을 만들어줘.
Base UI 컴포넌트를 우선 사용하고, 가능한 많은 적절한 컴포넌트를 사용해.
구현 후 디자인 시스템과 Base UI 사용 여부를 체크리스트로 검증해줘.

이 시나리오에서는 단순한 입력 폼만 만드는 것이 아니라, Base UI primitive와 디자인 시스템 적용 흐름이 함께 검증되어야 합니다.

권장 Base UI 후보는 다음과 같습니다.

Form, Field, Input: 이름, 이메일, 비밀번호, 에러 메시지 입력 구조
Checkbox: 약관 동의 또는 마케팅 수신 동의
Select: 국가, 직무, 관심 분야 같은 선택값
Button: 제출, 취소, 보조 액션
Tooltip 또는 Popover: 비밀번호 조건, 보조 설명
Dialog 또는 Alert Dialog: 제출 확인, 약관 상세, 오류 안내
Toast: 가입 성공 또는 실패 피드백

검증 체크리스트

테스트 결과는 다음 기준으로 확인합니다.

Base UI primitive를 우선 사용했는가?
사용한 Base UI 컴포넌트의 공식 문서를 MCP로 확인했는가?
design-system.md의 색상, typography, spacing, radius, elevation 기준을 반영했는가?
label, description, error message, focus state 등 접근성 구조가 있는가?
임의 색상값, 근거 없는 shadow, 근거 없는 radius, 장식용 gradient를 만들지 않았는가?
소비자 프로젝트의 기존 스타일 방식에 맞게 스타일을 적용했는가?
MCP validate_ui_code 또는 CLI validate를 실행했는가?
마지막 응답에서 사용한 Base UI 컴포넌트와 참고한 디자인 시스템 섹션을 요약했는가?

디자인 시스템 개발

로컬에서 패키지를 수정할 때는 의존성을 설치한 뒤 타입 검사, 테스트, 빌드, 검증을 순서대로 실행해 배포 가능한 상태인지 확인합니다.

컴포넌트 preview 화면은 preview 워크스페이스 앱으로 실행합니다. Base UI 컴포넌트와 아이콘 패키지가 실제 화면에서 함께 렌더링되는지 확인할 때 사용합니다.

pnpm preview

Vite 개발 서버가 출력하는 로컬 URL을 브라우저에서 열면 됩니다. 포트를 직접 지정해야 하면 preview 패키지에 인자를 전달합니다.

pnpm --filter @ncai/design-system-preview dev -- --port 5174

Vercel 미리보기 배포

이 저장소는 루트의 vercel.json으로 Vercel 배포 대상을 preview 앱으로 고정합니다.

Root Directory: preview
Install Command: cd .. && pnpm install --frozen-lockfile
Build Command: cd .. && pnpm --filter @ncai/design-system-preview build
Output Directory: dist

Vercel에서 GitHub 저장소를 Import할 때 Root Directory는 preview로 둡니다. preview/vercel.json은 monorepo 루트에서 의존성을 설치하고 preview 앱을 빌드한 뒤, Vercel 프로젝트 루트 기준 dist를 배포하도록 설정합니다. Vercel에서 생성된 Production Domain이 README 상단의 미리보기 링크와 다르면 해당 링크 URL만 실제 도메인으로 바꿉니다.

GitHub Actions에서도 main 브랜치 push마다 같은 preview를 Vercel production으로 강제 배포합니다. 저장소 Settings > Secrets and variables > Actions에 다음 값을 등록합니다.

VERCEL_TOKEN: Vercel Account Settings > Tokens에서 생성한 토큰
VERCEL_ORG_ID: Vercel Team 또는 Personal Account ID
VERCEL_PROJECT_ID: ncai-design-system Vercel Project ID

ID 값은 로컬에서 vercel link를 실행한 뒤 생성되는 .vercel/project.json에서도 확인할 수 있습니다. 이 파일은 로컬 연결 정보이므로 커밋하지 않습니다.

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm validate

수동 배포 절차

패키지 배포는 로컬 터미널에서 npm publish 또는 pnpm publish로 직접 실행하지 않습니다. .github/workflows/release.yml에서 검증 후 scripts/publish-missing.mjs를 실행하는 방식으로만 진행합니다. GitHub Actions는 repository secret NPM_TOKEN을 사용하며, 이 토큰은 npm publish 권한과 2FA publish 우회 권한을 가진 토큰이어야 합니다.

각 publish 대상 패키지는 prepublishOnly 훅으로 로컬 publish를 차단합니다. GitHub Actions의 Release workflow가 아닌 환경에서 npm publish 또는 pnpm publish를 실행하면 실패하며, 배포는 main 브랜치 push로 트리거해야 합니다.

개발자는 버전을 직접 여러 파일에서 찾아 바꾸지 않습니다. Changesets로 변경 내용을 기록하고 pnpm version-packages가 패키지 버전과 런타임 버전 상수를 함께 갱신하게 합니다.

예를 들어 packages/design-system을 수정한 뒤 배포하려면 다음 순서로 진행합니다.

pnpm changeset
pnpm version-packages
pnpm typecheck
pnpm test
pnpm build
pnpm validate
pnpm smoke:pack
git add .
git commit -m "Release design system updates"
git push

git push가 배포 트리거입니다. main에 push되면 GitHub Actions의 Release 워크플로가 전체 검증을 다시 실행하고, 아직 npm에 배포되지 않은 패키지만 공개 패키지로 게시합니다.

pnpm changeset을 실행하면 배포할 패키지와 버전 변경 수준을 선택합니다.

patch: 버그 수정, 문서 보강, 내부 구현 개선
minor: 새 기능, 새 명령, 새 MCP 도구, 사용 흐름 개선
major: 기존 사용 방식을 깨는 변경

pnpm version-packages는 생성된 changeset을 읽어 관련 package.json 버전을 갱신한 뒤 pnpm sync-versions를 실행합니다. 이 동기화 스크립트는 루트 package.json, packages/design-system/src/index.ts, packages/mcp/src/index.ts의 버전 상수를 패키지 버전에 맞춥니다. 따라서 버전 숫자를 여러 파일에서 직접 수정하지 않아도 됩니다.

배포 후에는 npm에서 버전을 확인합니다.

npm view @ncai/design-system version
npm view @ncai/design-system-icons version
npm view @ncai/design-system-cli version
npm view @ncai/design-system-mcp version
npm view @ncai/design-system-skills version

Windows PowerShell에서 npm.ps1 실행 정책 문제가 있으면 npm.cmd view ...처럼 npm.cmd를 사용합니다.

Name		Name	Last commit message	Last commit date
Latest commit History 64 Commits
.changeset		.changeset
.github/workflows		.github/workflows
packages		packages
preview		preview
resources		resources
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json
turbo.json		turbo.json
vercel.json		vercel.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

NC AI Design System

빠른 시작

아키텍처

패키지 구성

사용법

설치와 에이전트 설정

기존 프로젝트 업데이트

디자인 시스템 문서 조회

설치 상태 진단

UI 코드 검증

에이전트 작업 흐름

테스트 시나리오 예시

회원가입 화면으로 검증하기

검증 체크리스트

디자인 시스템 개발

Vercel 미리보기 배포

수동 배포 절차

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

NC AI Design System

빠른 시작

아키텍처

패키지 구성

사용법

설치와 에이전트 설정

기존 프로젝트 업데이트

디자인 시스템 문서 조회

설치 상태 진단

UI 코드 검증

에이전트 작업 흐름

테스트 시나리오 예시

회원가입 화면으로 검증하기

검증 체크리스트

디자인 시스템 개발

Vercel 미리보기 배포

수동 배포 절차

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages