네오-브루탈리스트 포트폴리오 키트
운영 중인 사이트에서 추출하여 테스트된 완전한 포트폴리오 템플릿입니다. 모든 파일은 assets/에 있으며, 새 Vite + React 프로젝트에 복사한 후 플레이스홀더 데이터를 소유자의 데이터로 바꾸면 바로 배포할 수 있습니다. 이 키트는 vite build가 처음부터 정상 작동하고 콘솔 오류 없이 렌더링되는 것이 확인되었습니다.
제공 항목
- 디자인 시스템 — 평평한 채도 색상, 3px 테두리, 단단한 오프셋 그림자, 기울어진 타일 (
assets/src/brutal/brutal.css,.nb범위 아래). - 섹션 — 로더 · 고정 네비게이션 (스크롤 스파이, 테마 + 언어 + 사운드 토글, 모바일 시트) · 글자별 호버 효과가 있는 히어로 · 소개 · 전체 화면 케이스 스터디 오버레이가 포함된 작업 그리드 (이전/다음, 키보드, 포커스 복원) · 스택 · 경력 아코디언 · 연락처 양식 · 실시간 로컬 시계가 있는 푸터.
- 이중 언어 + RTL — 논리적 CSS 속성을 사용한 영어/아랍어; 플래시 없이 라이트/다크 전환.
- 사운드 — 생성형 124 BPM 신스웨이브 루프 및 호버/클릭 효과 (각 히어로 글자는 펜타토닉 음을 냅니다). 오디오 파일 없음, 라이선스 불필요.
- 어시스턴트 —
api/chat.js기반의 플로팅 채팅: 소유자 데이터에 대한 RAG (아랍어 인식 BM25 + Gemini 임베딩), 근거 있는 답변, 모델 폴백, 동일 출처 + 속도 제한. API 키는 브라우저에 도달하지 않습니다. - 배포 설정 —
vercel.json(SPA 리라이트),.vercelignore.
빠른 시작 (새 프로젝트)
npm create vite@latest my-portfolio -- --template react를 실행하고assets/package.deps.json에 나열된 종속 항목을 설치하세요 (i18next react-i18next lenis framer-motion lucide-react @emailjs/browser @google/genai).assets/의 내용을 프로젝트 루트에 복사하세요 (src/병합,index.html및vite.config.js교체,api/,vercel.json,.vercelignore추가). 기본src/App.css/index.css임포트를 삭제하세요 — 키트가brutal.css를 통해 자체 CSS를 제공합니다.- 소유자의 데이터를 입력하세요 (개인화할 항목 참조).
- 포트릿 사진을
src/Imgs/portrait.jpg에 추가하고 프로젝트 스크린샷을public/projects/아래에 추가하세요 (WebP, 너비 ≤1280px). npm run dev→ 라이트/다크, EN/AR, 375px 및 1440px에서 확인하세요.npx vite build가 통과해야 합니다.- 배포:
references/deploy-and-secrets.md를 참조하세요.
개인화할 항목 (콘텐츠를 담고 있는 유일한 파일)
| 파일 | 입력해야 할 내용 |
|---|---|
src/data/siteFacts.js | 이름 (EN/AR), 히어로 이름 분할, 네비게이션 이니셜, 위치, 시간대, 연락처 링크, EmailJS 공개 ID, 기술 스택 열, 도구 |
src/data/projectsMeta.js | 프로젝트: 제목, 태그, 라이브 URL (또는 null), order, i18nIndex |
src/data/projectImages.js | 프로젝트별 스크린샷; 첫 번째 이미지는 카드 커버 |
src/i18n/locales/{en,ar}.json | 모든 텍스트 — 히어로 문장, 소개 텍스트/통계, 하이라이트, 경력, 프로젝트별 부제목/설명/화면 레이블, 프로젝트 "종류", 연락처 텍스트, 어시스턴트 프롬프트 |
index.html | <title>, 설명, 파비콘 |
데이터를 채울 때 규칙: 소유자만 확인할 수 있는 사실만 작성하세요. 고객, 숫자, 날짜 또는 링크를 절대 만들어 내지 마세요. 기술 이름은 두 언어 모두 영어로 유지하세요. 로케일 파일의 projects.items[i]는 i18nIndex와 일치해야 합니다.
디자인 언어 (요약 — 정확한 값은 references/design-system-spec.md 참조)
- 평평한 색상만 사용. 그라데이션, 글로우, 블러, 유리 효과 또는 보라색 "AI" 느낌 없음. 깊이 = 테두리 + 하드 섀도우.
- 테두리
3px solid var(--nb-line)· 그림자 단단한 오프셋 (5px/8px 8px 0, 호버 시12–14px) · 기울임-2°…2°, 호버 시 바로 정렬. - 타이포그래피: 디스플레이에는 Bricolage Grotesque 800 대문자, 본문에는 Space Grotesk, 레이블에는 JetBrains Mono 대문자. 아랍어: Cairo 700–900, 자간 없음, 대문자 없음.
- 대비 규칙: 채도가 높은 채움 위의 텍스트는 항상
#111이며 두 테마 모두에서#111테두리를 사용합니다. 중립적인 표면만 테마에 따라 전환됩니다. - 섹션 리듬: 히어로 노랑 → 소개 종이 → 작업 파랑 → 스택 종이 → 경력 라일락 → 연락처 분홍 → 푸터 검정.
--nb-*토큰을 변경하여 색상을 변경하세요. 리듬은 유지하세요.
엔지니어링 규칙 (편집 시 유지할 사항)
- 데이터 속성에 공개 상태 표시 (
data-reveal→data-in), 클래스 사용 금지 — React 리렌더링이 클래스를 덮어씁니다. - 케이스 오버레이는
data-lenis-prevent필요, 그렇지 않으면 Lenis가 내부에서 휠 스크롤을 차단합니다. 스크롤 가능한 오버레이(어시스턴트 채팅, 모바일 시트)에도 동일하게 적용됩니다. - 논리적 CSS 사용 (
inline-start/end,margin-inline), RTL에서 화살표 방향 전환, 숫자 카운터를dir="ltr"로 감싸기, 아랍어에 자간(letter-spacing) 절대 사용 금지. - 프로덕션 코드에서 절대
localhost를 호출하지 마세요 — 브라우저가 방문자에게 로컬 네트워크 권한을 요청합니다. URL 환경 변수가 설정된 경우에만 API를 호출하세요. - 성능: 아래 접힌 섹션은 지연 로딩;
loading="lazy"가 있는 WebP 이미지;transform/opacity만 애니메이션;prefers-reduced-motion존중; 공개 경로에 무거운 3D/UI 라이브러리 금지. - 비밀 정보: API 키는 서버 환경 변수 (
GEMINI_API_KEY)에만 있어야 합니다. 비밀 정보 앞에VITE_를 절대 붙이지 마세요 (브라우저에 번들링됩니다). 공개 EmailJS ID는 클라이언트 코드에서 사용해도 괜찮습니다. - 접근성: 보이는 포커스 링, 건너뛰기 링크, 토글에
aria-pressed, 오버레이에role="dialog"+ 포커스 복원, 축소 모션 지원.
"완료" 라고 말하기 전에 확인할 사항
npx vite build가 통과합니다.- 라이트 + 다크, EN + AR (RTL), 375px 및 1440px; 수평 오버플로우 없음.
- 케이스 스터디 열기 → 이전/다음/
Esc, 마우스 휠로 내부 스크롤. - 히어로 이름과 컨트롤을 (한 번 클릭 후) 호버하여 사운드 확인; 토글 상태 유지.
- 어시스턴트가 배포된 경우: 연락처 질문, 모든 프로젝트 목록 질문, 데이터에 없는 질문을 해보세요 (모른다고 대답해야 함).
- 미리보기 창이 숨겨질 수 있습니다(애니메이션 일시 중지) — 두 번째 스크린샷이나 실제 브라우저로 모션을 확인하세요.
디자인 시스템 아티팩트
DESIGN-SYSTEM.md— 개요 + 링크가 포함된 팔레트/규칙 표.design-system/tokens.css및tokens.json— React 키트 외부에서 사용하기 위한 토큰.design-system/styleguide.html— 라이브 스타일 가이드 (브라우저에서 열기): 대비가 포함된 팔레트, 타입 스케일, 그림자/기울임 스케일, 모든 컴포넌트, 모션, 권장/권장하지 않음.
참고 자료 (필요할 때 읽기)
references/design-system-spec.md— 정확한 디자인 시스템: 원칙, 모든 색상 및 적용 위치, 대비 수치, 타입 스케일, 간격, 그림자/테두리/기울임 스케일, 모션 토큰, z-index, 중단점, 컴포넌트 구조 및 상태.references/design-system.md— 클래스 카탈로그, 섹션 레시피, 색상 변경 또는 섹션 추가 방법.references/interaction-and-sound.md— 호버/클릭 동작, 공개 시스템, 음악 + SFX 아키텍처 및 튜닝.references/i18n-and-rtl.md— 로케일 구조, 키 맵, 아랍어 타이포그래피, RTL 체크리스트.references/assistant-rag.md— 채팅 엔드포인트 작동 방식, 지식 청크, 검색 및 프롬프트 튜닝.references/deploy-and-secrets.md— GitHub + Vercel 단계, 환경 변수, 키 교체, 문제 해결.