# CMSLAB ERP 디자인 가이드 v0.1

2026-09-09 · Proposed · 구현 전 검토용. 공식 CI, 원본 코어의 현재 규칙, 프로젝트 제안을 구분한다. AWS RDB 우선 방향에서도 이 화면·토큰 계약은 동일하게 적용한다.

[화면 표본 열기](CMSLAB_ERP_디자인_미리보기.html) · [공식 CI 원본과 근거](CMSLAB_CI_출처와원본자산.md) · [구현 지시 요약](DESIGN.md) · [제안 CSS 토큰](cmslab-tokens.proposed.css)

## 1. 목표: 브랜드는 명확하게, 업무 데이터는 빠르게 읽히게

CMSLAB의 신뢰·투명함을 정확한 상태, 원천·기준시각, 책임자, 변경 이력으로 표현한다. 붉은색은 브랜드와 중요한 실행을 식별하는 데 쓴다. 매일 수십~수백 행을 비교하는 제품·채널·출고 작업이 첫 화면의 중심이다. 홈페이지의 홍보 구성은 ERP에 그대로 옮기지 않는다.

‘AI 티’는 제작자를 판별할 수 있는 객관적 기준이 아니다. 이 문서에서는 **업무 맥락 없이 반복되는 장식·레이아웃·상태 표현**을 개선 대상으로 정의한다. 기본 서체나 shadcn 사용 자체가 결함은 아니다. 기존 키트의 표·접근성·상태 처리 동작을 살리면서 브랜드와 정보 우선순위를 구체화한다.

NN/G의 실제 디자인 과제 평가는 구체적인 요구·시각 참고를 제공하면 결과가 개선되지만, 정보 위계·그룹핑·색상 과용·대비·간격에 문제가 남을 수 있음을 보여준다. 이를 CMSLAB에서는 아래의 화면 검수 항목으로 바꾼다. 각 교정 규칙은 본 프로젝트의 제안이다. [연구 원문](https://www.nngroup.com/articles/ai-prototyping/)

## 2. 로고와 공식 색상

| 항목 | 적용 |
|---|---|
| 밝은 배경 | `assets/cmslab-logo-bright-bg.original.png` 그대로 사용 |
| 어두운 배경 | `assets/cmslab-logo-dark-bg.original.png` 그대로 사용 |
| 형태 | 원본 비율 2560:706. 왜곡·크롭·일부 추출·재조합·CSS filter·임의 색보정 금지 |
| 크기 제안 | 펼친 사이드바 가로 116px, 높이 자동. 여백 12px부터 검토. 공식 최소크기·보호공간은 미확보 |
| 브랜드 RED | 공식 HEX `#AF272F`를 디지털 초안에 사용 |
| 브랜드 LIGHT GREY | 공식 HEX `#A6A7A8`; 장식·브랜드 보조용. 작은 본문 색으로 쓰지 않음 |

공식 페이지의 RED RGB는 `191,48,26`, LIGHT GREY RGB는 `186,188,190`으로 각각 명시 HEX와 다르다. 이미지 픽셀도 별도 차이가 있다. HEX를 우선한 것은 잠정 프로젝트 선택이며 로고 파일은 원본 바이트를 보존한다. 인쇄용 Pantone/CMYK와 디지털 값을 임의 혼합하지 않는다. 상세 수치·출처·SHA-256은 [CI 근거 문서](CMSLAB_CI_출처와원본자산.md)에 있다. [공식 CI](https://www.cms-lab.co.kr/ci)

## 3. 화면에서 고칠 패턴

| 흔히 나오는 결과 | CMSLAB에서 생기는 문제 | 교정 규칙·검수 방법 |
|---|---|---|
| 환영 문구·대형 hero·KPI 카드 4개가 모든 화면 상단 | 검색·대사 표가 접힘 아래로 밀림 | 관리 화면은 제목→기준시각/범위→필터→표. KPI는 해당 결정을 돕는 경우에만 |
| 파란/보라 mesh·glass·번짐 그림자 | CI와 충돌하고 행·경계 판독 방해 | 셸·표·폼 불투명 면. 선택·오류 외 넓은 고채도 배경 제거 |
| 모든 행·그룹을 둥근 카드로 분리 | 나란히 비교 어려움, 스크롤 증가 | 반복 레코드는 DataTable. 상세 속성은 섹션·구분선. Card 중첩 금지 |
| 모든 버튼이 빨갛거나 화면에 CTA가 여러 개 | 현재 실행 우선순위 모호 | 페이지 primary 최대 1개, 나머지는 보조/텍스트. 삭제는 별도 위험 의미·확인 문맥 |
| 브랜드 빨강과 오류 빨강을 색으로만 구분 | 활성 메뉴가 오류처럼 보임 | 활성 항목은 배경·선·aria-current, 오류는 아이콘+정확한 문구. 색 단독 상태 금지 |
| ‘스마트 통합 플랫폼’ 등 일반 문구 | 사용자가 할 일·영향을 알 수 없음 | ‘미매핑 3건 확인’, ‘WMS 업로드 파일 생성’처럼 대상과 동사 표기 |
| 비어 있는 그래프에 그럴듯한 가짜 수치 | 미수령을 실측으로 오해 | 수령 전은 미수령, 연결 전은 미연결, 빈 결과는 0건. 표본은 합성 예시 표시 |
| 파일 생성 후 초록 ‘완료’ | ERP/WMS 실제 반영으로 오인 | 생성/전달/업로드 접수/반영 확인/대사 완료를 분리 |
| 화면마다 제각각 아이콘·sparkle·애니메이션 | 기능 의미 학습이 늘고 업무 집중 방해 | 키트 아이콘 한 계열. 아이콘만 버튼이면 접근 가능한 이름. 장식 회전/등장 효과 제거 |
| 길어진 상품명·코드 잘림, 마우스 hover만 상세 | 코드 대조 실패, 키보드·터치 사용 불가 | 본문 2줄 또는 상세보기. 전체 값은 포커스/복사/상세로 접근 가능 |
| 빈칸을 모두 회색 ‘-’ 처리 | 없음·미확인·권한 없음 혼동 | 데이터 없음/미수령/해당 없음/권한 없음 구분. 권한 밖 데이터는 응답 자체에서 제외 |
| 모든 기능을 챗봇·자유 프롬프트로 시작 | 반복 입력·승인·대사 재현성 약화 | 표·필터·정형 행동을 기본으로. AI 보조를 추가해도 수정 근거와 확정 단계를 별도 제공 |

‘남들과 달라 보이기’ 위해 중립색·표·통일된 radius를 금지하지 않는다. ECC의 `rules/web/design-quality.md` 중 장식적 깊이·색 변화 강제 지침은 채택하지 않는다. `frontend-design-direction`의 작업 중심·밀도·판독성 원칙만 선별한다. [ECC 선정 근거](../ECC/ECC_선별·도입가이드_2026-09-09.md)

## 4. 정보 구조와 화면별 필수 내용

메뉴 문구와 아래 영역은 IA 초안이다. 실제 메뉴는 코어의 메뉴 데이터로 관리하며 JSX에 권한별 메뉴 배열을 고정하지 않는다.

| 화면 | 주 작업·필수 열 | 상세/주의 |
|---|---|---|
| 제품마스터 | 분류군, 출시제품, ITEM 코드·이름, 용량·단위, 상태, 변경시각 | 분류 트리와 실물 목록 분리. 포장 revision/채널 구성/LOT은 상세 탭. BOM 종류 명시 |
| 채널 키 연결 | 채널, 판매계정, 코드종류, 원천코드, 옵션/단위, 대상 ITEM/offer, 유효기간, 확인상태 | ‘상품코드/바코드/주문행 참조’ 구별. 1:N 구성은 BOM 상세, 임의 복합문자열 키로 의미 숨기지 않음 |
| 출고 요청·대사 | 요청번호, 채널, 요청부서, 승인상태, 예약/재고 확인, 전달대상, 업로드 담당, 접수번호 | 실제 역할은 이관 적용일 기준. 원본 배치와 대상 파일·행 오류까지 추적 |
| 재고·LOT | 창고, ITEM, LOT, 유효기한, 실물/가용/예약/보류 수량, 단위, 기준시각 | LOT 미제공은 ‘원천 미제공’. 확정 0과 누락 구별. 채널 판매수량과 실물 수량 혼합 금지 |
| 주문기준 판매추이 | 주문일, 채널, 출시제품/ITEM/판매구성, 수량·주문수, 취소·반품, 기준시각 | 회계 매출로 명명하지 않음. 주문일/출고일/정산일을 한 날짜 선택지처럼 무심히 혼합하지 않음 |

판매추이 차트는 지표 정의·집계 단위·시간대·취소/반품 반영 방식·실측/추정·수령 범위를 표시한다. 원천을 못 받은 기간을 0으로 이어 그리지 않는다. 출시제품 비교 시 구성품 환산 정책을 명시하고 주문 건수는 구성품으로 펼친 뒤 중복 합산하지 않는다. 이 화면은 읽기 전용 시험 운영 후 보류할 수 있다.

원가·처방·BOM 민감 속성은 서버 권한으로 차단한다. 영업 화면에 원가를 숨기고 공헌이익을 그대로 노출해 역산 가능하게 만들지 않는다. Frozen/Slush/Liquid는 사용·변경 계약의 등급이며 세 단계 처리 진행률이나 세 가지 공개 권한으로 표현하지 않는다.

## 5. 토큰·글꼴·밀도

아래는 공식 CI 이외의 **프로젝트 제안 값**이다. [CSS](cmslab-tokens.proposed.css)는 표본용이며 현재 코어에 설치하지 않았다. 구현 때 코어의 기존 semantic token에 매핑하고 토큰 정본을 통일한다.

| 용도 | 밝은 테마 초안 | 의미 |
|---|---|---|
| 배경 / 표·폼 | `#F6F7F8` / `#FFFFFF` | 콘텐츠 구분, 불투명 |
| 본문 / 보조 본문 | `#25282B` / `#596168` | 브랜드 회색과 별도 |
| primary / primary 글자 | `#AF272F` / `#FFFFFF` | 핵심 실행 |
| 선택 배경 / 선택 글자 | `#FCEEEF` / `#AF272F` | 활성 메뉴·행 선택 |
| 장식 구분선 / 입력 경계 | `#D8DCDF` / `#80868C` | 입력 경계는 장식선과 별도 |
| 오류 / 성공 / 주의 / 정보 | `#B42318` / `#21633D` / `#805500` / `#245C85` | 텍스트·아이콘 병행 |
| 기본 radius | `0.375rem` | 둥근 윤곽 절제. 강도는 토큰으로 통일 |

로고 RED와 상태 error는 같은 토큰으로 묶지 않는다. 다크 테마에서도 원본 로고색은 손대지 않으며 본문·선택·경계용 색은 별도 검증한다. 다크 테마는 밝은 테마 색 반전으로 생성하지 않는다. 제안 CSS는 양 테마를 포함하지만 정식 컴포넌트 전체 검수 전 승인 완료로 보지 않는다.

Pretendard를 기존 구성에 맞게 사용한다. 서체 파일·라이선스와 한글 fallback은 구현 시 확인한다. 페이지 제목 20px, 섹션 16px, 본문/표 기본 14px, 보조 12px를 시작점으로 한다. 수치는 프로젝트 제안이다. 숫자는 같은 서체의 tabular-nums와 오른쪽 정렬, 단위는 열 제목/값에서 분명히 한다. 통화는 코어의 `Intl` 기반 ₩ 접두 규칙을 유지하되 판매추이 기본 지표는 금액이 아니다.

코어의 `components/erp/lib/density.ts`를 사용한다. 현재 rowH는 compact `h-8`, default `h-10`, relaxed `h-12`; 기본은 default. 크기를 화면마다 새로 하드코딩하지 않는다. 마우스 밀집 화면의 compact와 터치 조작은 별도로 검증하며 coarse pointer에는 코어 Responsive Contract의 44px 목표 영역을 유지한다.

## 6. 표·상태·반응형 계약

반복 데이터는 `@/components/erp`의 단일 DataTable을 사용한다. 검색·필터·정렬·컬럼 노출·선택·내보내기를 관련 작업 가까이에 배치한다. 일괄 행동은 선택 상태에서 대상 건수와 함께 표시한다. 이는 Carbon의 표 도구/선택 행동 지침을 참고한 적용이다. Carbon 라이브러리를 추가하는 제안은 아니다. [Carbon Data table](https://carbondesignsystem.com/components/data-table/usage/)

읽기 전용이면 DataTable 편집·추가·삭제·선택을 적절한 prop으로 해제한다. 컴포넌트 기본 CRUD 활성화를 업무 권한으로 간주하지 않는다. 합계는 현재 페이지/필터 결과/전체 중 범위를 명시한다. 외부 코드·주문번호는 앞자리 0을 보존한다. 내보내기도 화면과 같은 권한·필터·마스킹 계약을 적용한다.

| 상태 | 표시·동작 |
|---|---|
| 최초 로딩 | 표 구조 유지 skeleton, 이미 읽힌 데이터를 무조건 지우지 않음 |
| 0건 | ‘조건에 맞는 제품이 없습니다’와 필터 초기화 |
| 미수령·미연결 | 수령 여부·담당 업무 표시. 0으로 집계하지 않음 |
| 미매핑·검증 오류 | 행/열/원인/수정 방법, 오류 행 다운로드, 정상 행과 건수 구분 |
| 권한 없음 | 업무 존재 노출 범위도 정책 적용. 버튼 숨김 외 서버 조회·내보내기 차단 |
| 부분 반영·응답 불명 | 접수/확인 범위와 미확인 행 표시. 불명 상태 자동 재전송 금지 |
| 데이터 오래됨 | 원천 기준시각과 수집시각 분리. 지금 새로고침했다고 원천이 실시간인 것처럼 표시하지 않음 |

모바일 <640px, 태블릿 640–1023px, 데스크톱 ≥1024px의 기존 계약을 유지한다. 좁은 화면은 필터 접기·상세 세로 배치·테이블 내부 가로 스크롤을 사용한다. 문서 body 전체 가로 스크롤, 필수 컬럼 무조건 숨김, 모바일 전용 카드 그리드 재구현을 피한다. 필터·상태가 다른 탭에 남을 때는 현재 조직/권한과 맞는지 확인한다.

일반 텍스트는 배경 대비 4.5:1 이상, 큰 텍스트는 3:1 이상을 검수한다. 링크·버튼·필터의 키보드 접근, 보이는 포커스, 스크린리더 label, 확대 상태도 확인한다. 이 기준을 충족한 팔레트만으로 전체 WCAG 준수를 주장하지 않는다. [W3C 텍스트 대비 기준](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)

## 7. ERP Core에 적용할 파일과 순서

기준 커밋 `098fd338665de3f1a39ceb889a724f00079ddd91`. 경로는 형제 폴더 `erp-core/` 기준이다. 현재 소스는 수정하지 않았다.

| 파일·영역 | 적용 작업 |
|---|---|
| `lib/app-config.ts`, `ssot.config.json` | CMSLAB 앱 명칭·설명·brandStrings 정합. 이름 유래 쿠키 영향 검증 |
| `public/brand/` (추가 예정), 앱 셸·로그인 | 공식 원본 2종 복사·manifest 보존, 적합한 배경·비율 사용 |
| `app/globals.css`, `.gen-app/design-tokens.css` | blue 기반 semantic token을 CMSLAB 제안으로 매핑. 상태/차트/선택 토큰 분리 |
| `app/glass-surface.css` | `body::after` mesh 제거, `.glass-*` 불투명 면·단순 경계로 정리. hardcoded blur/saturate/shadow도 검토 |
| `app/(authed)/base/system/theme/design-set-defaults.ts` | 초기화/복원 값 변경. light/dark 양쪽 적용 |
| `contracts/theme.ts`, `lib/theme/queries.ts`, `app/_actions/theme.ts` | 현재 closed token set·검증·저장 정책 파악. AWS 저장소로 전환 시 동일 계약 보존 |
| `components/erp/shell/shell-providers.tsx` | ThemeTokenHydrator가 저장값을 inline CSS로 덮어쓰는 경로 확인. 테마 전환 시 이전 토큰 잔류 검증 |
| 기존 `supabase/seed.sql` 테마/관련 migration → AWS 초기 데이터 | 토큰 정본에서 초기 데이터 생성. 저장된 Blue Glass와 사용자 커스텀을 구분해 이행. 운영값 무조건 초기화 금지 |
| `.claude/rules/design-system.md`, `.claude/references/design-system-spec.md`, `docs/design-system/DESIGN-SYSTEM.md`, `CLAUDE.md` | Blue Glass 강제 규칙을 CMSLAB 규칙으로 동시 개정. 기존 DataTable/권한/반응형 계약 보존 |
| 기존 디자인/반응형/키트 테스트 | 새 토큰·로고·양 테마·로그인/표/폼/권한 없음 검증. 실패 테스트를 삭제해 통과시키지 않음 |

기존 규칙을 읽은 AI가 다시 glass·blue를 생성하지 않도록 코드와 지시 문서를 같은 변경 단위로 수정한다. 참고 CSS 파일을 최종 override로 영구 중첩하는 방식은 피한다. theme_tokens는 닫힌 키 집합이므로 필요한 semantic key 확장은 타입·초기값·저장소·hydrator·검증을 함께 바꾼다.

## 8. 구현 리뷰 통과 기준

1. 제품 이름이 길거나 미매핑·미수령·권한 없음일 때도 표의 주요 작업을 이해할 수 있다.
2. ‘출고 완료’ 같은 표현은 실제 접수·반영 증거와 일치한다. 상태 변화 책임자와 시각이 남는다.
3. 출시제품/실물/채널 구성/LOT의 관계가 화면에서 혼동되지 않는다.
4. 신규 화면이 키트의 표·밀도·반응형·키보드 동작을 보존한다.
5. 브랜드·상태·본문 토큰이 구분되고 밝은/어두운 테마 및 저장 테마 복원까지 검증한다.
6. 375/768/1440px에서 확인하고, 긴 데이터·수백 행·오류 다수·필터 결과 0건을 포함한다.
7. 원가·처방·민감 집계가 권한 밖 API 응답·내보내기·클라이언트 캐시에 존재하지 않는다.
8. 기존 코어의 권한 정적 검사 통과와 AWS 목표 시스템의 실제 권한 테스트 통과를 구분한다.

미리보기는 합성 데이터로 만든 독립 HTML 표본이다. 실제 Next.js 컴포넌트, 인증, AWS DB, ERP 연계가 구현된 화면은 아니다.

## 9. 이번 표본의 확인 기록

Chrome에서 검색·검색 0건·초기화·확인필요 필터·화면 전환·밀도·테마·로고 로딩을 확인했다. 1440px 밝은/어두운 테마와 375px 밝은 테마를 캡처해 검토했고 문서 body의 가로 넘침이 없었다. 모바일 표는 내부 스크롤한다. 정식 코어 컴포넌트나 스크린리더 전체 검수는 아직 수행하지 않았다. [동작 확인 기록](assets/design-preview-check.json)

불투명 sRGB 토큰 22개 조합의 대비를 계산했다. 밝은 배경에서 본문은 14.82:1, 보조 본문은 6.30:1, RED 버튼의 흰 글자는 6.66:1이다. 공식 LIGHT GREY와 흰색은 2.41:1이어서 작은 본문용으로 채택하지 않았다. 이 결과는 표본 토큰 쌍 검증이며 모든 화면 상태의 접근성 적합 판정은 아니다. [계산 결과](assets/token-contrast-check.json)