공통 UI 템플릿 및 포털 자유 레이아웃 가이드

목적: 모든 포털이 동일한 진입 경험과 기본 조작 규칙을 제공하면서도, 각 업무 화면의 레이아웃과 기능을 독립적으로 설계할 수 있도록 공통 UI의 책임 경계를 명확히 한다.

1. 기본 원칙

공통 UI는 포털 화면 전체를 하나의 고정 레이아웃으로 통제하지 않는다. 사용자가 로그인하고 업무 화면에 진입해 핵심 콘텐츠를 보기 전까지의 경험을 일관되게 제공하는 표준 템플릿을 담당한다. 그 아래의 업무 콘텐츠는 포털과 하위 페이지가 고유한 목적에 맞게 자유롭게 구성한다.

이 원칙은 두 가지를 동시에 보장한다. 사용자는 어느 포털을 방문해도 로그인, 메뉴 탐색, 화면 제목, 검색, 언어 전환, 첫 안내 영역을 익숙한 방식으로 사용한다. 반면 각 포털 팀은 업무 흐름, 데이터 밀도, 승인 절차, 게시판 구조에 맞게 히어로 아래의 화면을 제약 없이 설계할 수 있다.

구분	책임 주체	핵심 목적
표준 템플릿	공통 UI	모든 포털의 공통 진입 경험과 탐색 규칙을 통일
자유 레이아웃	포털·하위 페이지	업무 목적에 맞는 정보 구조, 화면 배치, 상호작용 구현
공통 컴포넌트	공통 UI	자유 레이아웃에서도 재사용 가능한 시각·상호작용 규칙 제공

2. 공통 UI 표준 템플릿 범위

표준 템플릿은 다음 네 영역으로 한정한다. 이 영역은 각 포털이 독자적으로 다시 구현하지 않고, @hohyun94/portal-foundation의 공통 프레임과 컴포넌트를 사용한다.

표준 영역	공통 UI가 제공하는 내용	포털이 전달하는 값
로그인 화면	로그인 카드, 상태 표현, 입력·오류·도움말의 기본 UI	인증 방식, 안내 문구, 인증 후 이동 경로
좌측 메뉴	브랜드 영역, 메뉴 계층, 접기·펴기, 활성 상태, 사용자 정보, 관리자 메뉴 진입	제품명, 메뉴 항목, 사용자 정보, 관리자 경로
우측 프레임 상단바	화면 제목, 전체 가로 구분선, 중앙 검색창, 우측 고정 KO / EN 토글	페이지 제목, 검색 처리 함수, 언어 전환 처리, 선택적 액션
히어로 영역	제목, 설명, 빠른 시작 액션, 숨김 제어, 개인화된 노출 설정	업무 맥락에 맞는 문구와 액션

2.1 좌측 메뉴의 운영 규칙

좌측 메뉴의 구조와 상호작용은 디렉토리서비스를 기준으로 한다. 펼친 상태에서는 브랜드·메뉴명·사용자 정보를 함께 표시하고, 접힌 상태에서는 아이콘 중심으로 축소한다. 관리자 메뉴는 사용자 정보 바로 위에 위치하며, 포털은 관리자 이동 경로 또는 클릭 처리만 제공한다.

각 포털은 현재 서비스 인지를 위해 일반 모드에서 좌측 메뉴의 배경색과 채도를 포털별 식별 테마로 지정할 수 있다. 다만 메뉴 폭, 접기·펴기 버튼, 아이콘 배치, 활성 상태, 사용자 정보 및 관리자 메뉴의 동작 규칙은 공통 UI를 따른다.

2.2 우측 상단바의 운영 규칙

우측 상단바는 제목, 검색, 언어 전환을 일정한 좌표로 제공한다. 제목은 좌측, 타원형 검색창은 중앙, 작은 KO / EN 토글은 오른쪽 끝에 고정한다. 각 포털은 검색 대상과 검색 결과 화면만 구현하고, 검색 입력 UI와 상단 정렬 규칙은 공통 UI를 사용한다.

2.3 히어로의 개인화 규칙

히어로는 포털의 첫 사용 경험과 주요 업무 맥락을 설명하는 표준 영역이다. 기본값은 첫 방문 시 노출이다. 사용자가 히어로의 숨김 기능을 선택하면, 그 선택은 해당 포털에만 개인화 설정으로 저장된다. 사용자는 설정 화면의 화면 구성 항목에서 언제든 다시 노출할 수 있다.

히어로는 모든 사용자가 기능의 존재를 알 수 있도록 기본 노출한다. 반복 업무 사용자는 필요에 따라 숨겨 콘텐츠 밀도를 높일 수 있다.

3. 히어로 아래의 자유 레이아웃

히어로 아래는 공통 프레임의 좌우 여백과 반응형 기본 규칙만 적용되는 자유 콘텐츠 영역이다. 이 영역의 그리드, 섹션 순서, 카드 배치, 데이터 표현 방식, 상세 화면 구성은 포털과 하위 페이지가 독립적으로 소유한다.

자유 레이아웃에서 포털이 결정하는 항목	예시
화면 정보 구조	대시보드, 트리·상세 2열 구조, 문서 열람 화면, 운영 콘솔
업무 흐름	승인 단계, 작성·검토·배포 절차, 검색 결과 탐색, 상태 전환
데이터 표현	표, 차트, 타임라인, 조직도, 프로세스 맵, 카드 목록
페이지별 반응형 구성	모바일 우선 순서, 접힘 패널, 좁은 화면의 데이터 축약
포털 고유 기능	업무 양식, 도메인별 필드, 정책 설정, 외부 시스템 연동

자유 레이아웃이라는 말은 시각 규칙을 포기한다는 뜻이 아니다. 포털은 레이아웃을 자유롭게 설계하되, 가능한 한 공통 UI의 기본 컴포넌트를 조합해 사용자 경험과 유지보수 비용을 함께 관리한다.

4. 자유 레이아웃에서 사용하는 공통 컴포넌트

아래 요소는 레이아웃 템플릿이 아니라 재사용 가능한 공통 컴포넌트로 제공한다. 포털은 자신의 화면 구조에 맞는 위치에서 이를 선택적으로 사용한다.

컴포넌트 분류	공통 제공 범위	포털의 확장 범위
버튼	톤, 크기, 상태, 아이콘 간격, 비활성·로딩 상태	업무별 문구, 이벤트, 화면 내 배치
타이포그래피	본문·제목·보조 텍스트의 기본 크기와 색상 단계	정보 위계, 페이지별 조합, 도메인 용어
상태 표시	성공·주의·오류·중립 배지와 알림 표현	상태 조건, 용어, 업무 규칙
첨부파일 UI	첨부 목록, 파일 메타데이터, 업로드·삭제 상태, 오류 표현	저장소, 보존 정책, 권한 검사, 파일 종류 제한
게시판 UI	목록, 상세, 작성, 빈 상태, 검색·필터 기본 요소	게시판 스키마, 승인 절차, 공개 범위, 데이터베이스
폼 요소	입력, 선택, 검증 메시지, 도움말, 액션 정렬	필드 구성, 유효성 규칙, 저장·승인 흐름

5. 구현 계약

포털의 기본 화면은 아래 순서로 구성한다. PortalFrame이 템플릿을 제공하고, PortalHero는 필요할 때 프레임 내부의 첫 콘텐츠로 사용한다. 히어로 다음부터는 포털이 자유롭게 콘텐츠를 구성한다.

import {
  PortalButton,
  PortalFrame,
  PortalHero,
} from "@hohyun94/portal-foundation";

export function PortalHome() {
  return (
    <PortalFrame
      productName="PROCESS CENTER"
      productMeta="WORKFLOW PORTAL"
      navigation={<PortalNavigation />}
      footer={<CurrentUser />}
      headerTitle="프로세스 라이브러리"
      adminHref="/admin"
      searchPlaceholder="프로세스 검색"
      onSearchSubmit={runProcessSearch}
      locale="ko"
      onLocaleChange={changeLocale}
    >
      <PortalHero
        eyebrow="QUICK START"
        title="업무를 빠르게 시작하세요"
        description="이 안내는 첫 방문에 표시되며, 필요하면 개인 설정으로 숨길 수 있습니다."
      >
        <PortalButton>프로세스 탐색</PortalButton>
      </PortalHero>

      {/* 여기부터는 포털·하위 페이지가 소유하는 자유 레이아웃입니다. */}
      <ProcessWorkspace />
    </PortalFrame>
  );
}

6. 적용 검토 기준

새 화면을 만들거나 기존 화면을 개편할 때, 다음 질문으로 책임 범위를 확인한다.

확인 질문	판단 기준
로그인 전 경험인가?	공통 UI의 로그인 컴포넌트를 우선 사용한다.
로그인 후 메뉴·헤더·히어로에 해당하는가?	표준 템플릿으로 구현한다.
히어로 아래의 업무 콘텐츠인가?	포털이 레이아웃과 흐름을 자유롭게 설계한다.
버튼·입력·첨부·게시판처럼 반복되는 요소인가?	공통 컴포넌트를 우선 검토하고, 부족한 부분만 확장한다.
포털 고유 데이터·권한·승인 정책인가?	포털이 자체 소스와 데이터 모델로 소유한다.

7. 변경 관리

표준 템플릿의 구조·동작·접근성·기본 토큰을 바꾸는 변경은 공통 UI 패키지에서 버전으로 관리한다. 포털은 해당 버전의 변경 내용을 검토한 뒤 배포 일정에 맞춰 의존성을 갱신한다. 자유 레이아웃의 개편은 포털 자체 변경으로 관리하며, 다른 포털에 자동 반영하지 않는다.

반복적으로 같은 형태로 구현되는 자유 영역 요소는 공통 컴포넌트 후보로 검토한다. 이 경우에도 먼저 컴포넌트 계약과 예제를 공통 UI에 추가하고, 전체 페이지 레이아웃을 고정 템플릿으로 승격하지 않는 것을 원칙으로 한다.

8. 관련 문서

• 팀원용 빠른 요약
• 발표용 슬라이드 프로젝트
• UiPlatform 아키텍처 원칙
• UiPlatform 결정 이력
• 공통 UI 패키지 저장소