design-refs — 작업 규칙 (rules)

상태·이력은 handoff.md, 규칙은 이 파일. 새 규칙이 생기면 그 답변에서 바로 🆕 신규에 1줄 append하고, 안정화되면 확립 규칙의 해당 §로 원문 이관한다.

📑 인덱스

2026-08-03 [페페] 디자인 레퍼런스는 C:\dev\design-refs\ 최상위에 모은다 — devplan 하위·tools 하위 아님. "dev 전체가 참고하는 자산"이라는 성격 때문이고, 소스가 늘어도 같은 틀(폴더 + 카탈로그 1항목)로 받는다. → §1·§2
2026-08-03 [코디] devplan 8799 서버는 코디가 재시작 못 하고 정션을 못 넘는다 — 그래서 devplan 밖 자산은 게시(복사)로 붙인다. → §3

상업적 사용이 자유로운 라이선스만: MIT · Apache-2.0 · CC-BY(표기 조건 확인). 유료 테마·NC(비상업)·평가판은 받지 않는다.
각 소스 폴더에 업스트림 LICENSE를 그대로 둔다(나중에 출처를 되짚을 수 있어야 한다).
받는 단위 = 오프라인으로 완결되는 것. CDN 링크만 적어두는 건 자산이 아니다(사무실 PC·오프라인에서 안 열린다).
원본 zip은 _raw\에 남긴다 — 재해제·버전 대조·무결성 확인에 쓴다.
업스트림 폴더 구조를 바꾸지 않는다. 예제가 상대경로(../assets/dist/css/...)로 서로를 참조하므로, 정리한다고 옮기면 그 순간 깨진다.

C:\dev\design-refs\<소스-버전>\ 에 압축 해제(구조 그대로 + LICENSE). 원본 zip은 _raw\.
build_catalog.py 의 SOURCES 에 항목 1개 추가 — 이름·버전·라이선스·홈페이지·태그·요약·assets(경로+설명+게시여부). 예제 페이지가 있으면 <id>-examples.json 리스트로 넣는다(slug·title_ko·category·what·components·best_for·path).
PYTHONUTF8=1 python build_catalog.py
PYTHONUTF8=1 python publish_devplan.py

파일 수·용량·아이콘 수를 수기로 적지 않는다 — build_catalog.py가 실측해 채운다(수기면 버전 올릴 때 반드시 어긋난다. devplan의 "건수 드리프트" 규칙과 같은 이유).
뷰어 페이지(devplan/design-refs.html)는 고치지 않는다 — catalog.json을 fetch해 그리므로 새 소스가 자동으로 뜬다. 페이지를 고쳐야 한다면 그건 카탈로그 스키마를 바꾼 것이다.
예제 분류는 파일을 실제로 열어보고 쓴다(서브에이전트에 맡길 때도 "이름만 보고 쓰지 마라"를 명시). components는 HTML에서 확인한 실제 클래스명만.

게시본 C:\dev\devplan\design-refs\ 는 산출물이다. 직접 편집 금지(다음 publish에 덮어쓴다). 차이 확인 = publish_devplan.py --check.
게시 대상 = 브라우저가 실제로 요청하는 것만(dist · examples · 아이콘 폰트/CSS/JSON · catalog.json). SCSS·소스맵(.map)·아이콘 SVG 2078개는 게시하지 않는다(아이콘은 웹폰트 CSS로 전부 렌더된다).
⚠devplan 8799 서버(app.py)는 상승권한 프로세스라 코디가 재시작할 수 없다 — 같은 계정인데 taskkill이 "액세스 거부". app.py를 고쳐도 즉시 반영되지 않는다(재시작이 필요한 변경은 페페 몫이거나 다음 부팅까지 대기).
⚠그 서버는 정션(mklink /J)을 못 넘어간다 — 실측: 같은 깊이 실디렉터리 200 / 정션 404. 새로 띄운 Python 3.12 http.server는 같은 정션을 200으로 서빙 → 서버 프로세스 권한 문제다. devplan 밖 폴더를 정션으로 붙이는 방법은 쓰지 마라.
app.py에는 /design-refs/* → C:\dev\design-refs 매핑 라우트가 들어 있다(경로 탈출 방어 포함). 서버가 재시작되면 그쪽이 우선인데 상대 경로가 같아 페이지는 어느 쪽이든 그대로 뜬다 — 게시 복사와 라우트는 충돌이 아니라 이중화다.

부트스트랩 전체 사용 = dist\css\bootstrap.min.css + dist\js\bootstrap.bundle.min.js 링크. devplan 페이지는 복사하지 말고 게시본 URL을 그대로 쓴다(/design-refs/bootstrap-5.3.8/dist/...) — 사본이 늘면 버전 올릴 때 어긋난다.
아이콘만 사용 = bootstrap-icons.min.css + fonts\ 폴더를 같이 복사(fonts 없으면 네모로 보인다). devplan은 게시본 링크.
~~⚠devplan 페이지 자체에는 부트스트랩 CSS를 링크하지 않는다~~ 2026-08-03 페페 지시로 폐기 — devplan UI 자체가 부트스트랩으로 간다. 테라코타는 devplan/assets/theme.css의 --bs-* 브리지가 지키고(링크 순서 부트스트랩 → theme.css → 페이지 style), check_theme.py는 벤더 CSS를 판정에서 제외한다. (원래 근거: 부트스트랩 팔레트가 웜톤을 덮어써 게이트 FAIL. 남의 예제 원본을 보여줄 땐 지금도 iframe 격리가 맞다.)
조각을 베꼈으면 어떤 예제에서 가져왔는지 한 줄 남긴다(다음에 같은 화면을 다시 만들 때 시간을 번다).
2026-08-03 examples/dashboard(navbar + offcanvas-md 사이드바 + col-md-9 ms-sm-auto col-lg-10 본문) → devplan 메인 허브 index.html(생성기 build_hub.py). 첫 소비처. 사이드바 배경은 바깥 col에 줘야 한다(예제가 두 군데 다 배경 클래스를 준 이유 = md↑에서 offcanvas가 background:transparent !important).