빌드 케이스: 시길 CSS 가이드 사이트¶

바이브 코딩으로 사이트 만들기 - 첫 번째 케이스 (2026-02) 상태: 진행 중 (카드 데이터 추가 단계)

프로젝트 개요¶

사이트: https://sigil-css-guide.vercel.app
목적: 시길(Sigil) 전자책 CSS 가이드 + 레퍼런스. 초보자 학습 + 본인 작업 참조 + 강의 교재
핵심 기능: CSS 카드 카탈로그, 코드 복사(주석 포함/코드만), 라이브 미리보기, 뷰어 호환성 뱃지

기술 스택¶

선택	이유
Astro 5.x	정적 콘텐츠 사이트에 최적
순수 CSS + 최소 JS	외부 의존성 0
Vercel	GitHub push → 자동 배포, 무료

ai-prompt 사이트와의 차이점¶

항목	sigil-css-guide (1차)	ai-prompt (2차)
콘텐츠 형식	페이지별 카드 배열 (하드코딩)	Content Collections (마크다운)
상세 패널	DetailPanel 컴포넌트 분리	interactions.ts에서 동적 생성
미리보기	iframe 라이브 미리보기	없음 (텍스트 프롬프트라 불필요)
뱃지	뷰어 호환성 + 접근성 (자동 계산)	AI 역할 (수동 지정)
카테고리	페이지별 분리 (headings, body 등)	categories.ts 중앙 관리

프로젝트 구조¶

src/
├── components/
│   ├── CSSCard.astro        ← CSS 카드 썸네일
│   ├── DetailPanel.astro    ← 상세 패널 (6페이지 공유)
│   └── PreviewCard.astro    ← 미리보기 카드
├── layouts/BaseLayout.astro
├── pages/                   ← 카테고리별 페이지 14개
│   ├── index.astro
│   ├── headings.astro, body.astro, boxes.astro ...
│   ├── compatibility.astro, troubleshooting.astro, workflow.astro
│   └── test.astro
├── scripts/detail-panel.ts  ← 패널 인터랙션
├── styles/global.css
└── types/card.ts            ← CardData 타입 정의

핵심 설계 결정들¶

1. DetailPanel 컴포넌트 분리¶

처음에 6개 페이지에 패널 HTML 중복 → 컴포넌트 1개로 통합
ai-prompt에서는 JS로 동적 생성하는 다른 방식 채택

2. CardData 타입¶

TypeScript 타입으로 카드 데이터 구조 강제
뷰어 호환성, 접근성 등급 등 복잡한 메타데이터 관리

3. 코드 안 주석 = 조작 가이드¶

/* 숫자↑ 두꺼워짐 */ 같은 주석으로 비개발자도 수정 가능
코드 설명(접이식)은 이해 가이드 역할

1차에서 배운 것 → 2차에 적용¶

1차 경험	2차 개선
카드 데이터 하드코딩 → 수정 번거로움	Content Collections 마크다운 도입
DetailPanel 컴포넌트 분리에 시간 소요	처음부터 JS 동적 생성으로 설계
Vercel 이메일 불일치 삽질	배포 전 체크리스트 만들어서 방지
페이지마다 카드 배열 관리	categories.ts 중앙화

현재 상태¶

프레임워크/컴포넌트/배포 완성
카드 데이터 본격 추가 단계 (03-CSS-레퍼런스.md 기반)
참조 데이터: D:\ebook-project\_docs\03-CSS-레퍼런스.md