App Shell UI
당신은 App Shell UI를 구현하고 있습니다: 두 가지 모드를 가진 재사용 가능한 프론트엔드 디자인 스킬입니다. 픽셀을 선택하기 전에 표면을 선택하세요. 모든 요청을 데스크톱 셸로 만들지 말고, 모든 앱을 일반 마케팅 페이지로 만들지 마세요.
먼저 표면을 선택하세요
| 모드 | 사용처 | 기본 구조 | 사용하지 말아야 할 곳 |
|---|---|---|---|
| 앱 모드 | 로그인된 도구, 설정, 콘솔, 채팅, 메일, 작업대, 운영 워크플로우 | 고정된 왼쪽 탐색 + 작업 캔버스 | 공개 마케팅, 읽기, 상거래, 또는 포트폴리오 표면 |
| 웹사이트 모드 | 마케팅 사이트, 제품 출시, 포트폴리오, 에디토리얼 페이지, 카탈로그, 문서, 공개 콘텐츠 | 사용자 여정에서 선택된 페이지별 매크로 구조 | 일반 히어로 + 세 개의 카드 + CTA 템플릿, 또는 가짜 앱 셸 |
요청에 두 표면이 모두 있는 경우 별도로 디자인하세요: 획득 또는 공개 정보를 위한 웹사이트 모드, 로그인된 제품을 위한 앱 모드. 적절한 경우 브랜드 토큰을 공유하되, 두 모드에 동일한 레이아웃이나 밀도를 강제하지 마세요.
사전 점검 (두 모드 모두)
기존 프로젝트에서 시각적 결정을 내리기 전에, 경로와 가장 가까운 시각적 진실 공급원(현재 토큰, 타이포그래피, 테마 메커니즘, 에셋, 프레임워크, 컴포넌트 기본 요소, 설치된 아이콘/모션 라이브러리)을 검사하세요. 사용자가 리디자인을 요청하지 않는 한 기존 시스템을 유지하세요. 의존성을 추가하기 전에 package.json을 확인하고, 라이브러리가 존재한다고 가정하거나 하나의 표면에 두 개의 관련 없는 디자인 시스템을 혼합하지 마세요.
브리핑이 실질적으로 다른 두 결과 사이에서 진정으로 모호한 경우, 정확히 한 가지 짧은 질문을 하세요. 그렇지 않으면 한 문장으로 추론을 명시하고 계속 진행하세요. 작은 구현 요청을 요구 사항 인터뷰로 만들지 마세요.
앱 모드 워크플로우
- 레이아웃 템플릿 선택 (픽셀 전 필수):
- 설정형 — 좁은 왼쪽 탐색 + 폼 / 토글 목록
- 콘솔형 — 왼쪽 탐색 + 카드 그리드 / 상태 목록
- 작업대형 — 세션 트리 + 중앙 빈 상태 + 컴포저 카드
- IM / 세 칸형 — 아이콘 레일 + 목록 + 상세
- 뷰포트 예산 설정 — 대상 데스크톱 뷰포트(최소 1280×800)와 콘텐츠를 추가하기 전에 경로의 기본 작업 하나를 정의합니다.
references/layouts.md→ Viewport budget / 단일 페이지 용량을 참조하세요. - 듀얼 테마 토큰 잠금 —
references/tokens.md를 사용합니다(라이트 + 다크는 기본적으로 모두 필요). - 레시피로 구성 —
references/components.md(탐색 항목, 카드, 목록 행, 토글, 알약, 빈 상태/컴포저)를 사용합니다. 레시피는 테마에 구애받지 않습니다. 변수만 변경됩니다. - 구현 CSS 변수 +
data-theme="light"|"dark"로 구현하고, 테마 토글을 추가합니다. Tailwind/shadcn 매핑은 선택 사항입니다. - 자체 점검 — 전달 전에 두 테마와 대상 뷰포트에서 이 파일 끝에 있는 체크리스트를 실행합니다.
자유롭게 선택할 수 있는 기본 스택:
| 계층 | 기본값 |
|---|---|
| 마크업 | 시맨틱 HTML 또는 React |
| 스타일 | CSS 변수 + 경량 유틸리티/Tailwind |
| 컴포넌트 | shadcn / @coss 스타일 (New York + 아연 같은 중성색) |
| 아이콘 | Lucide 스타일 1.5–2px 스트로크, 하나의 패밀리만 |
| 테마 | 라이트 + 다크 (토글 + 선택 사항 OS prefers-color-scheme) |
데모에는 사용자가 프로젝트 통합을 원하지 않는 한 단일 자체 포함 HTML을 선호합니다.
앱 모드 아키텍처
L0 창 크롬 (선택 사항 신호등 / 제목 표시줄 / 상단 도구 + 테마 토글)
L1 사이드바 또는 아이콘 레일
L2 콘텐츠 캔버스 (부드러운 회색 라이트 / 부드러운 차콜 다크)
L3 표면 (떠 있는 카드, 패널, 목록)
사이드바 너비: 220–260px(텍스트 탐색) 또는 48–56px(아이콘 레일). 콘텐츠 패딩: 20–28px. 4px 그리드의 간격.
기본 페이지 예산: 초기 데스크톱 상태는 셸 크롬을 포함한 후 하나의 뷰포트에서 기본 작업을 완료해야 합니다. 작은 하단 여백을 유지하고, 일상적인 보조 콘텐츠를 표시하기 위해 페이지 전체를 세로로 스크롤하지 마세요. 긴 컬렉션은 제품이 진정으로 필요로 할 때 하나의 제한된 내부 스크롤 영역을 사용할 수 있습니다. 중국어 선호: 각 페이지가 가능한 한 한 화면에 완성되고, 콘텐츠가 첫 화면 용량에 도달하면 더 이상 쌓기를 중단합니다.
앱 모드 필수 사항
- 두 가지 테마: 사용자가 명시적으로 하나만 원하지 않는 한 라이트 및 다크 토큰 세트를 제공합니다.
- 하나의 브랜드 기본 색상: 기본 버튼, 토글 ON, 진행률 채우기, 선택된 테두리/배경, 링크에 사용합니다. 다크 기본 색상은 약간 더 밝은 쌍일 수 있습니다(예:
#007AFF→#0A84FF). - 표면 계층(두 테마 모두): 앱 배경 → 사이드바 배경 → 떠 있는 표면(약한 대비). 라이트: 부드러운 회색 + 흰색 카드. 다크: 부드러운 차콜 + 올라간 회색 카드 — 순수
#000페이지 + 순수#fff카드가 아닙니다. - 텍스트 계층: 기본 / 보조 / 3차 (값은 테마마다 다름).
- 계층 구조: 먼저 1px 테두리를 사용하고, 그림자는 선택 사항이며 테마에 따라 다릅니다.
- 둥근 모서리 계층: 8 / 12 / 16 / 999 (테마 간 공유).
- 복사 패턴: 제목 + 하나의 음영 처리된 부제목 줄.
- 모션: 150–200ms 색상/배경만 사용, 바운스 연출 금지.
- 테마 전환: 루트에
data-theme+ 표시 가능한 토글, 가능하면localStorage로 지속성을 유지합니다. - 아이콘 절제(콘텐츠): 오른쪽 콘텐츠는 기본적으로 텍스트 + 스트로크 아이콘 + 상태 알약입니다. 이모지/일러스트레이션은 선택적 악센트로만 사용하며, 모든 목록 행이나 카드의 기본값이 아닙니다. 밀집된 목록에서는 이모지 제로를 선호하고, 배너나 빈 상태에서 최대 하나의 장식 마크만 사용합니다.
- 동일 높이 동료: 나란히 있는 콘텐츠 쌍(목록 + 컴포저, 패널 + 패널, 한 행에 카드 쌍을 이루는 통계 형제)은 동일한 외부 하단 가장자리를 공유해야 합니다.
align-items: start로 인해 하나의 짧은 카드가 발생하지 않도록 그리드/flexstretch+ 열 flex + 표면에flex: 1을 사용하세요.references/layouts.md→ Equal-height side-by-side columns를 참조하세요. - 단일 뷰포트 콘텐츠 예산: 데스크톱에서 기본 경로는 페이지 수준의 세로 스크롤이 필요하지 않아야 합니다. 우선 순위가 있는 콘텐츠로 사용 가능한 캔버스를 채우되, 첫 번째 뷰포트를 초과하기 전에 중단하세요. 콘텐츠가 맞지 않으면 제거, 단축, 페이지 매김, 공개, 탭 분할 또는 다른 경로로 분할하고, 컨트롤을 자르거나 가독성 이하로 텍스트를 축소하지 마세요. 모바일에서는 기본 작업과 상태를 첫 번째 뷰포트에 유지하고, 진정으로 긴 콘텐츠를 위해 자연스러운 스크롤을 예약하세요.
앱 모드 Do / Don't
| Do | Don't |
|---|---|
| 왼쪽 탐색 + 오른쪽 콘텐츠 | 앱 전체를 덮는 전체 너비 히어로 아트 |
| 두 테마 모두 부드러운 캔버스 + 떠 있는 카드 | 기본값으로 네온 사이버 다크 또는 순수 OLED 블랙 |
| 단일 강조색 (라이트/다크 쌍) | 여러 기본 색상으로 무지개 탐색 아이콘 |
| 탐색 + 콘텐츠에 스트로크 아이콘 (Lucide 스타일) | 혼합된 채움 + 스트로크 아이콘 세트 |
| 텍스트 우선 카드/목록, 상태 표시용 알약 | 모든 행 / 카드 / 섹션 헤더에 이모지 |
| 크롬 내 상태 표시를 작은 알약 / 음영 처리된 텍스트로 | 정상 상태에 대한 시끄러운 전체 너비 경고 배너 |
| 크롬 내 테마 토글 | filter: invert()를 통한 다크 모드 |
| 토큰을 통한 테두리 분리 | 하드 코딩된 #fff / #000 크롬 색상 |
| 여유로운 간격 | 빽빽한 스프레드시트 패킹 |
| 주요 영역당 ≤1개의 이모지 악센트 (또는 없음) | 배너 + 카드 + 목록 모두 이모지 과다 |
| 나란한 카드 동일 높이 (stretch) | 하나는 길고 하나는 짧은 짝 (align-items: start) |
| 우선 순위 블록으로 한 화면 경로 | 일상적인 콘텐츠에 대한 무제한 페이지 스크롤 |
| 긴 컬렉션에 대한 제한된 내부 스크롤 | 고정 높이로 콘텐츠 숨기기 또는 자르기 |
앱 모드 페이지 조립 순서
- 셸 (창 + 사이드바 + 메인)
- 사이드바의 브랜드 블록
- 탐색 그룹 + 활성 항목
- 페이지 헤더 (H1 + 음영 처리된 부제목 + 작업)
- 제목 표시줄 또는 설정의 테마 토글 (데모에 필수)
- 선택 사항 도구 모음 (검색 + 분할 필터)
- 우선 순위별 콘텐츠 블록: 배너 → 통계 → 기본 그리드/목록 → 보조 2열. 뷰포트 예산이 가득 차면 중단, 낮은 우선 순위 블록을 탭, 공개, 페이지 매김 또는 다른 경로로 이동.
- 모든 2열 동료 행에 대해: 동일 높이 레시피 적용 (stretch + flex 표면) 오버플로우 강제 없이.
- 상호 작용 연결: 탐색 전환, 선택, 토글, 필터, 테마 토글
앱 모드 구현 노트
- 라이트 토큰은
:root, :root[data-theme="light"]에, 다크 토큰은:root[data-theme="dark"]에 배치 (references/tokens.md참조). - 컴포넌트는 변수만 사용 — 컴포넌트 규칙에 하드 코딩된 브랜드/표면 16진수 금지.
- 선택된 탐색: 부드러운 기본 색상 워시 + 기본 텍스트, 둥근 모서리 8px (워시 혼합은 테마마다 다름).
- 카드:
--bg-surface+ 1px--border+ 둥근 모서리 12, 선택됨: 기본 색상 링/테두리. 선행 마크 = 음영 처리된 판의 스트로크 아이콘 또는 마크 없음 — 기본적으로 이모지 아님. - 설정 / 피드 행: 16–18px 스트로크 아이콘 (선택 사항 부드러운 판) + 제목 + 음영 처리된 설명 + 오른쪽 컨트롤. 이모지 목록 아이콘 피하기.
- 빈 / 새 세션: 중앙 제목 + 큰 둥근 컴포저 + 칩 + 기본 CTA. 빈 워터마크는 하나의 희미한 스트로크 아이콘 또는 단일 음영 처리된 글리프일 수 있음 — 이모지 스택이 아님.
- 배너: 텍스트 우선, 선택 사항 최대 하나의 작은 악센트 타일 (종종 없음).
- "빈 컬렉션 + 생성"을 위한 점선 추가 영역 (더하기 기호, 이모지 아님).
- 보조 버튼, 세그먼트 트랙, 토글 OFF 트랙은 테마 토큰을 사용해야 함 (
--secondary-btn-bg,--seg-track,--toggle-off) — 밝은 회색 rgba는 다크에서 작동하지 않습니다. - 페이지 셸을 기본적으로 고정(
min-height: 0; overflow: hidden)으로 유지합니다. 목록, 로그, 테이블 또는 메시지 기록이 본질적으로 긴 경우 명확한 높이 예산으로 하나의 제한된 하위 영역에 스크롤을 적용합니다. 문서 본문이나 전체 콘텐츠 캔버스를 기본 스크롤 컨테이너로 만들지 마세요. - 최소 1280×800의 데스크톱 뷰포트(및 좁은 모바일 뷰포트)에서 첫 로드 상태를 확인합니다. 기본 작업, 컨트롤 및 상태가 페이지 스크롤 없이 표시되고 텍스트나 컨트롤이 잘리지 않는지 확인합니다.
테마 API (표준)
// data-theme = "light" | "dark"
// localStorage key: "app-shell-theme"
// 토글은 속성을 전환하고, 초기화는 storage를 읽은 다음 prefers-color-scheme을 읽습니다.
최소 CSS 토큰 블록
references/tokens.md에서 듀얼 테마 블록을 복사합니다.
최소 HTML 스켈레톤
<html data-theme="light">
…
<div class="window">
<header class="titlebar">
…
<button type="button" data-theme-toggle aria-label=""]색상 모드 전환">…</button>
</header>
<div class="shell">
<aside class="sidebar">…</aside>
<main class="main">…</main>
</div>
</div>
앱 모드 프롬프트 시드
라이트
macOS 데스크톱 유틸리티 라이트 UI: 240px 부드러운 회색 사이드바 (스트로크 아이콘 + 레이블, 선택됨 = 밝은 기본 색상 워시 + 8px 둥근 모서리), 메인 캔버스 부드러운 회색에 흰색 둥근 카드; 버튼, 토글, 진행률, 선택 링에 단일 기본 #007AFF; 세 가지 텍스트 회색; 둥근 모서리 8–16px; 그림자 거의 없음, 1px 밝은 테두리; 설정/목록 행에 작은 스트로크 아이콘 (이모지 아님) + 제목/설명 + 오른쪽 토글 또는 상태 알약; 콘텐츠 영역 텍스트 우선, 이모지 최소 또는 없음; 빈 상태 = 중앙 제목 + 큰 둥근 컴포저.
다크
동일한 셸 다크 모드: 부드러운 차콜 캔버스 #1C1C1E, 사이드바 #161617, 떠 있는 카드 #2C2C2E, 테두리 흰색 8% 알파, 텍스트 #F5F5F7 / #A1A1A6 / #6C6C70, 기본 #0A84FF, 선택된 탐색 = 카드 표면에 기본 22% 혼합; 순수 검은색 페이지 없음; 반전 필터 없음; 테마 토글 포함.
비즈니스 명사만 변경하고 셸 + 듀얼 테마 규칙은 유지합니다.
웹사이트 모드 워크플로우
웹사이트 모드는 공개 웹 작업을 위한 것입니다. 일반 문서 스크롤을 사용할 수 있으며 앱 모드의 고정 캔버스, 사이드바, 인공 창 크롬 또는 단일 뷰포트 콘텐츠 제한을 상속하지 않아야 합니다. 웹사이트 모드를 구현하기 전에 references/web-frontend.md를 읽으세요.
- 디자인 판독 — 페이지 종류, 대상, 기본 작업 및 구체적인 톤을 명시합니다. "깔끔하고 현대적인"은 방향이 아닙니다. 브리핑과 기존 브랜드에서 추론하고, 두 방향이 실질적으로 다른 작업을 생성하는 경우에만 한 가지 짧은 질문을 합니다.
- 표면 모드 선택 — 전환 페이지 또는 출시를 위한 설득, 문서 또는 에디토리얼 콘텐츠를 위한 읽기, 포트폴리오/갤러리/이벤트 작업을 위한 경험, 또는 탐색 및 구매를 위한 카탈로그. 로그인한 제품은 앱 모드에 유지됩니다.
- 컴포넌트 전에 매크로 구조 선택 — 작업에 맞는 페이지 모양을 선택합니다. 예: 제품 공개, 증거 기반 스토리, 에디토리얼 내러티브, 작업 인덱스, 카탈로그, 읽기 가이드 또는 캠페인 포스터. 중앙 히어로 -> 세 개의 동일한 카드 -> CTA를 기본값으로 사용하지 마세요.
- 시각 시스템 확정 — 팔레트, 유형 역할, 간격/둥근 모서리 규칙, 이미지 처리 및 하나의 눈에 띄는 차별화 요소를 고정합니다. 기존 브랜드 토큰을 재사용하고, 그렇지 않으면 시맨틱 CSS 변수를 정의하고 섹션별로 색상이나 서체를 즉흥적으로 지정하지 않고 사용합니다.
- 진실과 미디어 계획 — 제공된 사실, 실제 스크린샷/제품 상태, 라이선스 자산 또는 브리핑에 적합한 생성된 비트맵 시각 자료를 사용합니다. 고객, 지표, 사용후기, 로고, 가짜 대시보드, 브라우저 크롬 또는 실제로 읽히는 플레이스홀더 데이터를 발명하지 마세요. 알 수 없는 주장은 플레이스홀더로 표시되거나 생략됩니다.
- 정보 여정 구축 — 시맨틱 랜드마크와 다음 작업을 명확하게 하는 계층 구조를 사용합니다. 작업이 다른 경우 섹션의 구성이 달라질 수 있습니다. 카드는 반복적이고 제한된 항목을 위한 것이며 페이지 섹션의 기본 래퍼가 아닙니다.
- 완전한 동작 구현 — 관련된 경우 기본 컨트롤 및 링크, 표시 가능한 포커스, 로딩, 빈 상태, 오류, 비활성화 및 성공 상태를 사용합니다. 모션은 피드백이나 공간 변화를 설명해야 하며,
transform/opacity를 사용하고,prefers-reduced-motion을 존중하며, 사실상 즉각적이지 않는 한 고빈도 흐름에서 멀리 떨어져 있어야 합니다. - 렌더링된 출력 검사 — 데스크톱 및 모바일 스크린샷, 실제 콘텐츠 극단, 대비, 키보드 탐색, 로딩 이미지 크기, 오버플로우 및 첫 번째 뷰포트의 유효성을 검사합니다. 히어로의 제안, 기본 작업 및 시각적 초점은 1280x800에 맞아야 합니다. 그 아래 페이지 스크롤은 웹사이트에서 정상입니다.
웹사이트 모드 필수 사항
- 사용자가 명시적으로 제품 미리보기 또는 로그인된 애플리케이션 경로를 요청하지 않는 한 공개 웹사이트를 앱 모드 크롬으로 감싸지 마세요.
- 모든 공개 페이지에 시맨틱 HTML 랜드마크, 탐색 가능한 제목 구조 및 포커스 표시를 제공합니다.