@uniai-fe/uds-templates

v0.0.13

Published

9 hours ago

UNIAI Design System; UI Templates Package

Downloads

1,285

0High
0Medium
0Low

kdh0824

uniaicorp

graffitoryu

@uniai-fe/uds-templates

@uniai-fe/uds-foundation 토큰과 @uniai-fe/uds-primitives 기초 컴포넌트를 조합해, 서비스 앱에서 자주 반복되는 화면/플로우 템플릿을 제공하는 패키지입니다.

Next.js 서비스에서 primitives와 동일한 방식으로 Raw TypeScript 형태로 소비되며, pnpm transpilePackages 설정을 통해 빌드 파이프라인에 포함됩니다.

Peer Dependencies

@uniai-fe/uds-foundation@^0.0.1 (CSS 토큰 + reset)
@uniai-fe/uds-primitives@^0.0.2 (템플릿 내부 UI 컴포넌트)
react >= 19, react-dom >= 19
Storybook/로컬 개발용으로는 @uniai-fe/uds-foundation/css를 앱 루트에서 한 번만 import 해야 합니다.

템플릿은 primitives 위에서 동작하므로, @uniai-fe/uds-primitives가 설치되어 있지 않으면 빌드 타임에 peer dependency 경고가 발생합니다.

특징

화면 단위 템플릿:
- 로그인/회원가입/아이디·비밀번호 찾기 등 /auth/**
- 로그인 이후 화면을 위한 모바일 페이지 프레임 /page-frame/mobile(PC는 추후 /page-frame/pc)
Raw TS 배포:
- package.json exports가 src/**를 가리키며, 번들 없이 즉시 import 가능한 형태로 제공합니다.
디자인시스템 일관성:
- 스타일은 항상 @uniai-fe/uds-foundation/css에서 제공하는 CSS 변수(토큰)를 통해만 정의됩니다.
- UI 요소는 모두 @uniai-fe/uds-primitives 컴포넌트를 조합해 구성합니다.
역할 분리:
- templates는 레이아웃/플로우/상태 표현까지 담당하고,
- API 호출, 인증 토큰 관리, 라우팅, i18n 등 비즈니스 로직은 서비스 앱에서 구현합니다.

현재 제공 템플릿/모듈

/auth/**
- 로그인 화면 템플릿 (Login)
- 회원가입 플로우 템플릿 (Sign Up, step 기반)
- 아이디 찾기 템플릿
- 비밀번호 찾기/재설정 템플릿
/page-frame/**
- /page-frame/mobile: 로그인 이후 화면을 위한 모바일 프레임(header/body/footer)
- /page-frame/pc: 추후 확장 예정
/modal/**
- ui-legacy 스택 기반 모달 Provider/Root/Container + 템플릿(Modal.Alert, Modal.Dialog)
- Storybook(apps/design-storybook/src/stories/templates/modal)에서 Alert/Confirm 케이스를 검증한다.

각 템플릿의 상세한 범위와 의사결정은 CONTEXT-*.md 문서에서 관리합니다.

회원가입 Step 구조

Step1 — User Info (name + phone): 기본 정보 입력. PhoneInput은 인증 UI 없이 마스킹만 제공한다.
Step2 — Verify & Agreement: 약관 동의 + EmailInput(인증요청/타이머/OneTimeCode). alert/confirm는 서비스 앱이 직접 처리한다.
Step3 — Generate Account: username/password/confirm + password 조건 helper.
Step4 — Complete: 승인 대기 안내. CTA 명칭은 “Complete”만 사용한다.

세부 props/스토리 구성은 docs/CONTEXT-SIGNUP.md, docs/CONTEXT-SIGNUP-FLOW.md, docs/STORYBOOK.md에서 확인하고 변경 시 세 문서를 동시에 업데이트한다.

설치 & 기본 설정(Next.js 예시)

pnpm add @uniai-fe/uds-foundation @uniai-fe/uds-primitives @uniai-fe/uds-templates

1) transpilePackages 설정

// next.config.ts
const nextConfig = {
  transpilePackages: [
    "@uniai-fe/uds-foundation",
    "@uniai-fe/uds-primitives",
    "@uniai-fe/uds-templates",
  ],
};

export default nextConfig;

2) 스타일 전역 주입

템플릿은 primitives 위에 구성되므로, 앱 루트에서 @uniai-fe/uds-templates/styles(Sass) 또는 @uniai-fe/uds-templates/css(번들 CSS) 중 하나를 한 번만 import 하면 foundation 토큰, primitives, templates 스타일이 모두 초기화됩니다.

/* app/globals.scss (Sass 사용 프로젝트) */
@use "@uniai-fe/uds-templates/styles";

// app/layout.tsx (Sass 비사용 프로젝트)
import "@uniai-fe/uds-templates/css";

export default function RootLayout(props: { children: React.ReactNode }) {
  return (
    <html lang="ko">
      <body>{props.children}</body>
    </html>
  );
}

간단 사용 예시

// app/(auth)/login/page.tsx
import { AuthLoginTemplate } from "@uniai-fe/uds-templates/auth";

export default function LoginPage() {
  return (
    <AuthLoginTemplate
      text={{
        title: "로그인",
        description: "서비스 이용을 위해 로그인해 주세요.",
      }}
      logoSlot={<img src="/logo.svg" alt="서비스 로고" />}
      onSubmit={async (values) => {
        // 실제 로그인 API 호출은 서비스 앱에서 구현
        // await login(values);
      }}
    />
  );
}

위 예시는 개념을 설명하기 위한 형태이며, 실제 props 구조/이름은 CONTEXT-AUTH.md에서 확정·관리합니다.

Modal 모듈 사용법

ui-legacy에서 사용하던 모달 스택/옵션을 templates 레이어로 옮겨왔습니다. 핵심 흐름은 다음과 같습니다.

Provider 1회 장착 — 서비스 레이아웃에서 <Modal.Provider />를 렌더합니다.
훅 사용 — const { newModal, closeModal } = Modal.useModal();
템플릿 팩토리 — Modal.Alert, Modal.Dialog이 ModalState 객체를 반환하므로 newModal(...)에 그대로 전달합니다.

// app/layout.tsx
import "@uniai-fe/uds-templates/styles";
import { Modal } from "@uniai-fe/uds-templates/modal";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="ko">
      <body>
        {children}
        <Modal.Provider />
      </body>
    </html>
  );
}

// 예: Alert/Confirm 호출
import { Modal } from "@uniai-fe/uds-templates/modal";

export function ExampleActions() {
  const { newModal } = Modal.useModal();

  const openAlert = () =>
    newModal(
      Modal.Alert({
        stackKey: "sample/alert",
        message: "필수 항목 동의에 체크해 주세요.",
        confirm: { label: "확인" },
      }),
    );

  const openConfirm = () =>
    newModal(
      Modal.Dialog({
        stackKey: "sample/confirm",
        title: "저장하시겠어요?",
        content: "입력한 내용이 저장되며 되돌릴 수 없습니다.",
        confirm: {
          label: "저장",
          onClick: () => {
            // 서비스 동작
          },
        },
        cancel: { label: "취소" },
      }),
    );

  return (
    <>
      <button onClick={openAlert}>Alert</button>
      <button onClick={openConfirm}>Confirm</button>
    </>
  );
}

footer 버튼은 ui-legacy와 동일하게 stackKey, role, defaultOptions/linkOptions 구조로 관리하며, Alert(Text)/Dialog(Solid) 규격은 templates 내부에서 보장합니다.
세부 가드레일·확장 기록은 CONTEXT-MODAL.md를 참고하고, 새 템플릿을 추가할 때 해당 문서를 선행 업데이트합니다.

Scripts

패키지 루트에서 실행 가능한 대표 명령:

pnpm module:lint — ESLint 전역 규칙 점검
pnpm module:typecheck — TS 타입 검사 (tsconfig.build.json 기준)
pnpm module:build — lint → typecheck 순으로 배포 전 검증
pnpm design-templates:dev — 타입 검사 watch 모드

모노레포 루트에서는 pnpm --filter @uniai-fe/uds-templates <command> 또는 pnpm modules:build(turbo run)으로 전체 패키지를 빌드할 수 있습니다.

문서

CONTEXT.md — templates 패키지 전체 상황/진행 현황 인덱스
CONTEXT-GUIDELINES.md — templates 전역 규칙(슬롯/반응형/page-frame 적용 범위 등)
CONTEXT-AUTH.md — /auth/** 템플릿 범위/디자인 근거/Figma 링크
CONTEXT-SIGNUP.md, CONTEXT-SIGNUP-FLOW.md — 회원가입 단계/훅/스토리 전략 및 Figma node 표
CONTEXT-PAGE-FRAME.md — /page-frame/** 템플릿 범위/디자인 근거
FOUNDATION-USAGE-GUIDE.md — 템플릿에서 design-foundation 토큰을 사용하는 규칙
PRIMITIVES-USAGE-GUIDE.md — 템플릿에서 design-primitives를 사용하는 규칙
STORYBOOK.md — templates Storybook 가이드(로그인/회원가입/페이지 프레임 시나리오)

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@uniai-fe/uds-templates

Peer Dependencies

특징

현재 제공 템플릿/모듈

회원가입 Step 구조

설치 & 기본 설정(Next.js 예시)

1) transpilePackages 설정

2) 스타일 전역 주입

간단 사용 예시

Modal 모듈 사용법

Scripts

문서