website

Imported from woowabros/critical-script (docs/website/AGENTS.md). Install upstream with npx skills add woowabros/critical-script --skill website. Copyright stays with the author.

문서 사이트 작업 규칙

docs/website/ 아래에서 작업할 때 따르는 규칙입니다.

컴포넌트 폴더 컨벤션

컴포넌트 하나가 폴더 하나를 갖고, 그 컴포넌트만 쓰는 것은 모두 그 안에 둡니다.

src/components/BenchmarkStage/
  index.ts                 배럴, 기본 내보내기만
  BenchmarkStage.tsx       컴포넌트
  BenchmarkStage.css.ts    스타일
  useBenchmark.ts          이 컴포넌트만 쓰는 유틸리티

index.ts 는 한 줄입니다. 밖에서는 폴더 이름으로 가져오므로 파일 구조가 바뀌어도 부르는 쪽이 흔들리지 않습니다.

export { default } from './BenchmarkStage'

import BenchmarkStage from '../website/src/components/BenchmarkStage'

무엇을 폴더 안에 두고 무엇을 밖에 둘까

읽는 곳이 하나면 그 폴더 안에, 여럿이면 밖에 둡니다.

컴포넌트가 다른 컴포넌트의 파일을 읽는 것은 괜찮습니다. Showcase 가 ../Waterfall/lanes 를 읽고, BenchmarkStage 가 ../Waterfall 을 렌더링합니다. 이때는 폴더 이름까지 적어서 어느 컴포넌트의 것인지 드러냅니다.

lib/ 에 남는 것은 지금 두 개입니다. demo.ts 는 네 컴포넌트와 레이아웃, 스타일시트가 함께 읽고, i18n.ts 는 모든 컴포넌트가 읽습니다.

스타일

스타일은 vanilla-extract 로 쓰고 컴포넌트 옆에 둡니다. 값은 styles/tokens.css 가 갖고 있고, styles/vars.css.ts 가 그 이름을 타입스크립트에서 부를 수 있게 이어 줍니다. 팔레트를 여기서 다시 선언하지 않습니다.

네임스페이스로 가져오고 이름은 styles 로 씁니다. vanilla-extract 저장소와 Braid 가 자기 코드에서 쓰는 방식입니다. 나눠 쓰는 스타일시트는 그 파일을 가리키는 이름으로 받습니다.

import * as chart from '../../styles/chart.css'
import * as styles from './Waterfall.css'

합성한 스타일과 원본 스타일이 같은 속성을 정하지 않게 합니다. styleVariants 로 합성하면 두 클래스가 한 요소에 붙고, 같은 속성을 양쪽이 정했을 때 어느 쪽이 이기는지는 스타일시트에 쓰인 순서에 달립니다. 그 순서가 개발 서버와 빌드에서 다릅니다. Waterfall.css.ts 의 frame 이 상태마다 테두리를 직접 선언하는 이유입니다.

d3 가 붙이는 클래스는 전역 스타일시트에 둡니다. 차트는 실행 시점에 클래스 이름을 문자열로 만들어 붙이므로, styles/chart.css.ts 에서 이름을 만들어 그리는 코드에 넘깁니다.

문구

화면에 나오는 모든 문구는 src/lib/i18n.ts 에 있습니다. 한국어와 영어를 함께 고칩니다. 한쪽만 고치면 두 언어가 다른 이야기를 합니다.

문서 원본은 docs/en/, docs/ko/ 에 있습니다. 404 페이지는 src/pages/404.astro 에 구현합니다. src/content/docs 아래에 사본을 만들지 않습니다.

벤치마크 페이지의 제목과 설명은 예외적으로 두 곳에 있습니다. Starlight 가 제목을 문자 그대로 읽어야 해서 페이지 프런트매터에도 같은 문장이 필요합니다. 한쪽을 고치면 다른 쪽도 고쳐야 합니다.

확인

pnpm typecheck 와 pnpm build 를 통과해야 합니다. 타입스크립트 파일은 Prettier 서식을 지키고, docs/en/ 과 docs/ko/ 의 마크다운은 서식을 적용하지 않은 상태로 관리되고 있으니 건드리지 않습니다.

개발 서버가 vanilla-extract 의 파일 스코프를 잃거나 콘텐츠 목록을 찾지 못하면, 파일을 옮기거나 설정을 바꾼 뒤 캐시가 어긋난 것입니다. node_modules/.vite 와 .astro 를 지우고 다시 띄우면 해결됩니다.