/home/ec2-user/copilot/hyperbook 정적 웹 스타터 구조 분석

1. 분석 범위

대상은 /home/ec2-user/copilot/hyperbook 디렉터리의 다음 파일이다.

• index.html
• styles.css
• script.js
• stackbit.config.ts
• README.md
• .gitattributes

이 디렉터리는 현재 8765 포트에서 실행 중인 hyperbook-site 서비스의 디렉터리와 별개인 소스 저장소다.

2. 전체 구조

이 프로젝트는 별도 빌드 도구 없이 브라우저가 직접 제공할 수 있는 정적 웹페이지다. index.html이 문서 구조와 콘텐츠를 정의하고, styles.css가 시각 표현을 담당하며, script.js가 연도 표시와 버튼 동작을 추가한다. package.json이나 애플리케이션 서버는 보이지 않으므로 기본 실행 모델은 파일 서버 또는 정적 호스팅이다.

3. HTML 분석

index.html은 HTML5 문서이며 viewport 메타 태그와 외부 CSS·JavaScript 연결을 포함한다. 페이지는 헤더, 본문, 푸터로 나뉜다. 헤더에는 Hyperbook 제목과 A fresh start for your project.라는 tagline이 있고, 본문에는 환영 카드와 cta-btn 버튼이 있다. 푸터의 year 요소는 JavaScript가 현재 연도로 채운다.

현재 lang 속성은 en이며 콘텐츠도 영어다. 한국어 콘텐츠를 추가할 경우 언어 속성 변경, 번역 구조화, 긴 문자열에 대한 레이아웃 검증이 필요하다. 이미지·폼·라우팅·데이터 바인딩은 없다.

4. CSS 분석

스타일은 전역 CSS 변수 대신 :root에 색상 체계와 시스템 폰트를 설정한다. box-sizing: border-box를 전역 적용하고, body를 최소 화면 높이의 flex 컨테이너로 만들어 헤더와 푸터 사이에서 .content가 남은 공간을 차지하도록 구성했다.

헤더와 푸터는 파란색에서 청록색으로 이어지는 gradient를 사용한다. 본문은 grid의 place-items: center로 카드를 중앙 배치하고, 카드에는 최대 너비 560px, 둥근 모서리, 그림자를 적용했다. 버튼에는 hover·active 상태와 짧은 transform 효과가 있다. 반응형 기본 요소는 갖췄지만, 고대비·키보드 포커스·모션 감소 설정은 별도로 다루지 않는다.

5. JavaScript 분석

스크립트는 year와 cta-btn 요소를 조회한 뒤 각 요소가 존재할 때만 동작을 등록한다. 연도는 브라우저의 현재 날짜에서 계산되므로 매년 콘텐츠 수정 없이 갱신된다. 버튼 클릭 시 alert로 Your project is ready to build on!을 표시한다.

요소 존재 여부를 검사하는 방어적 구조는 부분 템플릿 재사용에 유리하다. 반면 alert는 확장성이 낮고 테스트·접근성·사용자 경험 측면에서 제한적이다. 향후에는 상태 메시지를 DOM에 표시하거나 실제 CTA 동작으로 대체할 수 있다.

6. Stackbit 설정

stackbit.config.ts는 Stackbit 타입의 defineStackbitConfig를 사용한다. Stackbit 버전 계열은 ~0.6.0, Node 버전은 18, SSG 이름은 custom으로 지정되어 있다. contentSources는 빈 배열이므로 CMS나 외부 콘텐츠 소스와 연결되지 않는다. postInstallCommand는 @stackbit/types를 저장하지 않고 설치한다.

따라서 현재 설정은 콘텐츠 모델을 제공하는 완성된 CMS 프로젝트라기보다, Stackbit 인식 가능성을 남겨 둔 최소 정적 스타터 설정에 가깝다. 콘텐츠 관리가 필요하면 데이터 모델과 content source, 빌드·미리보기 명령을 명시해야 한다.

7. 저장소 및 운영 특성

.gitattributes는 텍스트 파일을 자동 감지하고 LF 줄바꿈으로 정규화한다. 이는 운영체제별 줄바꿈 차이로 인한 불필요한 diff를 줄인다. README.md는 프로젝트 이름만 포함한 최소 문서이므로 실행 방법, 포트, 배포 절차, 브라우저 지원 범위, 기여 규칙을 보강할 여지가 크다.

8. 개선 우선순위

1. README에 정적 서버 실행 및 배포 절차를 추가한다.
2. 버튼의 alert를 의미 있는 링크, 폼, 또는 인라인 상태 메시지로 교체한다.
3. :focus-visible 스타일과 prefers-reduced-motion 처리를 추가한다.
4. 언어와 콘텐츠를 명확히 하고 필요하면 lang=ko 또는 다국어 구조를 도입한다.
5. Stackbit을 실제로 사용할 계획이라면 content source와 콘텐츠 스키마를 연결한다.
6. HTML 검증, CSS 검사, JavaScript 동작 검사를 자동화한다.

결론

이 저장소는 의존성이 거의 없는, 이해하기 쉬운 정적 Hyperbook 시작점이다. 문서·스타일·상호작용의 책임이 파일별로 분리되어 있고, 브라우저에서 즉시 제공할 수 있다는 점이 장점이다. 반면 콘텐츠 관리, 빌드·배포 자동화, 접근성 세부사항, 테스트 및 운영 문서가 아직 최소 수준이므로 실제 서비스로 확장하려면 이 영역을 순차적으로 보강해야 한다.