설치와 토큰 적용

Podo UI는 기본 디자인으로 바로 시작할 수 있고, 준비가 되면 같은 코드를 유지한 채 팀의 Figma 토큰으로 바꿀 수 있어요. 먼저 아래에서 사용하는 환경을 고르고 첫 화면을 띄워 보세요.

1. 패키지를 설치하고 첫 화면 띄우기

모든 환경에서 설치 명령은 npm i podo-ui 하나입니다. 탭을 고른 뒤 코드를 앱의 시작점에 넣으세요. Next.js와 Hono는 첫 HTML에도 테마 속성을 넣어 두면 화면이 뜨는 순간부터 올바른 색이 보입니다.

1// 터미널: npm i podo-ui2import { Button, PodoThemeProvider } from "podo-ui/react";3import "podo-ui/styles.css";4import "podo-ui/icons.css";5
6export function App() {7  return (8    <PodoThemeProvider theme="landing" colorScheme="light" applyToDocument>9      <Button theme="solid-primary">저장</Button>10    </PodoThemeProvider>11  );12}

2. 앱 전체에 테마 한 번 적용하기

화면마다 테마를 반복하지 않아도 됩니다. 앱 루트에서 landing 또는 dashboard와 light 또는 dark를 한 번 정하세요. React의 applyToDocument는 모달처럼 body로 이동하는 UI도 같은 토큰을 쓰게 하고, 서버 렌더링은 HTML에 속성을 미리 넣어 첫 화면의 깜빡임을 막습니다.

1<!-- 준비:2  npx podo-ui init --target web --theme landing --out-dir public/podo --yes3  npx podo-ui build4  cp node_modules/podo-ui/styles.css public/podo/styles.css5  public 폴더를 사이트의 정적 루트로 제공합니다.6-->7<html lang="ko" data-podo-theme="landing" data-color-scheme="light">8  <head>9    <link rel="stylesheet" href="/podo/styles.css" />10    <link rel="stylesheet" href="/podo/tokens.css" />11    <link rel="stylesheet" href="/podo/components.css" />12  </head>13  <body>...</body>14</html>

3. 어디서든 디자인 토큰 사용하기

Podo 컴포넌트 밖의 화면도 같은 디자인 언어로 만들 수 있어요. 웹에서는 생성된 tokens.css를 시작점에서 한 번 불러오고 --podo-* CSS 변수를 사용하세요. 색상뿐 아니라 간격, 반경, 타이포그래피까지 루트 테마를 따라 자동으로 바뀝니다. React Native에서는 Provider에 넣은 토큰을 usePodoNativeTokens로 꺼냅니다.

전역 토큰으로 만든 계정 카드

1/* tokens.css를 HTML에서 한 번 불러온 뒤 어느 스타일시트에서나 사용합니다. */2.account-card {3  color: var(--podo-text-basic);4  background: var(--podo-elevation-basic);5  border: 1px solid var(--podo-border-gary);6  border-radius: var(--podo-radius-control-md);7  padding: var(--podo-spacing-scale-8);8  font-family: var(--podo-typography-body-medium-fontFamily);9  font-size: var(--podo-typography-body-medium-fontSize);10  line-height: var(--podo-typography-body-medium-lineHeight);11}

4. 팀 디자인을 가져오고 싶을 때

기본 테마만 쓴다면 여기까지면 충분합니다. 팀 토큰이 필요하면 먼저 npx podo-ui init --target react --theme landing --out-dir src/podo --yes로 .podo를 만드세요. 그다음 import를 대기시킨 뒤 플러그인에서 ‘프로젝트로 보내기’를 누르면 CLI가 변경 내용을 먼저 보여 줍니다. Next.js와 Hono CSR도 target react를, Hono SSR은 hono를, React Native는 native를 사용합니다.

하려는 일	순서	결과
새 Figma 파일에 설치	플러그인 → PODO 디자인 시스템 설치	_podo 페이지, 변수·스타일·컴포넌트
코드 프로젝트에 적용	npx podo-ui init → npx podo-ui import → 프로젝트로 보내기	.podo 입력과 검토 가능한 변경 계획
파일로 백업·복원	고급 도구 → JSON 내보내기/가져오기	.podo-export.json

5. 변경 내용을 확인하고 토큰 만들기

먼저 검증하고, dry-run으로 바뀔 파일을 살펴본 다음 실제 생성하세요. 만들어진 CSS·TypeScript·폰트는 언제든 .podo의 JSON에서 다시 만들 수 있으므로 직접 고치지 않는 것이 안전합니다.

명령	역할
`npx podo-ui init --target react --theme landing --out-dir src/podo --yes`	처음 한 번 .podo 작업 공간 만들기
`npx podo-ui import`	Figma 변경 계획을 받고 확인 후 적용
`npx podo-ui validate`	JSON 스키마·참조·아이콘 입력 검증
`npx podo-ui build --dry-run`	생성/갱신 파일 계획 확인
`npx podo-ui build`	확인한 토큰·컴포넌트·아이콘 생성

환경마다 어디까지 쓸 수 있나요?

React와 Next.js는 같은 컴포넌트를 사용합니다. Hono의 기본 UI는 서버에서 바로 만들 수 있고, DatePicker와 Editor처럼 브라우저 상태가 필요한 화면만 React island로 붙입니다. React Native는 네이티브 UI와 WebView 기반 Editor를 제공합니다. 전역 토큰은 아래 모든 환경과 일반 HTML/CSS에서 사용할 수 있습니다.

환경	기본 컴포넌트	DatePicker	Editor
React	전체	전체	전체
Next.js	전체 (SSR/Client)	use client	use client
Hono	15개 정적 SSR	React island	React island
React Native	Native UI	Native modal	react-native-webview