아이콘이 없어 텍스트로 대체돼 있던 자리를 시안대로 되돌린다. `@fox`에 Phosphor 전량이
들어왔으므로 더 이상 막힐 이유가 없다.
- students: 돋보기(FoxMagnifyingGlassIcon) — "조회" 텍스트 버튼을 대체
- admins · boards · decoration-items: 연필(FoxPencilSimpleIcon)·휴지통(FoxTrashIcon)
- 테마 토글: 손으로 그린 monitor/moon/sun 3종을 @fox 아이콘으로 교체하고
components/ui/icons/ 디렉터리를 제거했다(다른 사용처 없음)
버튼을 `components/ui/button`이 아니라 `FoxIconButton`으로 쓴 이유 — @fox 아이콘은 스스로
크기를 갖지 않고 감싼 슬롯이 정하는 규약인데, 그 슬롯 크기를 실제로 정의하는 CSS가 있는 건
@fox 쪽뿐이다. Tailwind 제거(e3d3133)가 빌드 설정만 바꾸고 components/ui 19개 파일은 그대로
둔 탓에 `size-9`·`inline-flex` 같은 클래스가 전부 무효라, 그쪽에 아이콘을 넣으면 SVG가 기본
300×150으로 그려진다.
테마 토글은 같은 이유로 실제 버그였다 — 표시 전환을 Tailwind의 `hidden theme-*:contents`에
기대고 있어서 세 아이콘이 한꺼번에 보이고 있었다. 같은 동작을 CSS 모듈로 다시 세웠고,
`aria-label` 대신 `sr-only` 텍스트로 현재 선택을 읽히는 기존 접근성 설계는 그대로 유지했다
(IconButton에 label을 넘기면 aria-label이 내용을 덮어쓴다).
검증 — 컴파일된 CSS를 주입해 `` 3상태를 실제로 전환했다. 속성 없음→system,
light→light, dark→dark로 **매번 하나만** 표시되고 20×20px(--fox-icon-4)로 그려진다.
FoxIconButton은 sm/ghost에서 28px 버튼에 24×24 아이콘이다.
남은 것 — sidebar-group.tsx의 셰브론은 손으로 그린 채로 뒀다. 회전(`rotate-90`)과
크기(`size-4`)를 Tailwind 클래스에 기대고 있어 그 둘을 실재하는 CSS로 옮기기 전에는 글리프만
바꿔도 나아지지 않는다. components/ui 전체 리스타일과 함께 처리한다.
Co-Authored-By: Claude Opus 5
시안의 `ico/*`는 Phosphor Icons를 그대로 올린 것이다. `ico/House` Regular와 Phosphor
`house.svg`는 문 너비 16.67%·문 span 25%·벽 두께 8.33%가 전부 같고, 프레임 구조도
`Format=Stroke|Outline × Weight=Thin|Light|Regular|Bold|Fill|Duotone`으로 Phosphor의
weight 체계 그대로다. 그래서 Figma를 1,512번 호출하는 대신 원본에서 생성했다.
- @fox/tools/build-icons.py 신설. build-tokens.py와 같은 자리·같은 철학(Figma가 SSOT이고
생성물은 재현 가능)이다. 실행 1.4초.
- core/icons/glyphs/*.tsx 1,512개 + fox-icon.tsx(공용 껍데기) + index.ts 배럴.
기존 icons.tsx(8종 수기 이식)는 이 안에 포함되므로 삭제했다.
- 굵기를 이름이 아니라 `weight` prop으로 바꿨다. 시안의 `Weight=` 변형과 1:1이다.
FoxCaretLeftBoldIcon → .
- viewBox를 Phosphor 원본의 256으로 통일했다. 기존 8종은 Figma export라 16/24 박스에
translate가 붙어 있었지만 같은 그림을 축소한 것이다(House bbox x=32 → 32/256×16=2로
기존 translate와 일치).
검증 — 기존 8종과 새 생성물을 256×256으로 래스터화해 픽셀 비교했다. 차이가 잉크의 0.33%
이하(안티에일리어싱 경계)였고 Pause는 0픽셀이었다. weight 매핑이 유일한지도 오답을 넣어
확인했다: Play를 regular로 두면 58.4%, bold면 60.7%, Plus를 regular로 두면 34.0% 어긋난다.
즉 시안의 Play·Pause는 fill, Plus는 bold다 — 이름에 표시가 없어 놓치기 쉬운 지점이라
fox-carousel-button 주석과 README에 명시했다.
번들 — 배럴이 크지만 프로덕션에는 쓰는 글리프만 들어간다(안 쓰는 아이콘의 path 문자열이
프로덕션 .js 어디에도 없음을 확인). build 6초, tsc 3초로 영향 없다.
라이선스 — Phosphor는 MIT다. 사본에 고지를 함께 두도록 요구하므로 생성기가 원본 LICENSE를
core/icons/PHOSPHOR-LICENSE.txt로 옮긴다.
Co-Authored-By: Claude Opus 5
@fox 토큰이 패밀리명을 리터럴 `Pretendard`로 지정하는데 프로젝트 어디에도 그 이름의 폰트
공급이 없었다. 그래서 모든 @fox 컴포넌트가 OS 기본 서체(맥 Apple SD Gothic Neo / 윈도
맑은 고딕)로 갈라져 그려졌고, 글자 폭이 시안과 어긋났다.
- public/fonts: Pretendard v1.3.9 woff2 400/600/800 반입(OFL 1.1). 토큰이 쓰는 weight가
정확히 이 셋이다 — 특히 800은 wantedSans에 없어 가짜 굵기로 합성되고 있었다.
- globals.scss: @font-face로 직접 선언. next/font/local은 패밀리명을 해시로 바꿔 토큰의
리터럴과 만나지 못해 이 용도로는 쓸 수 없다.
- globals.scss: body에 `--app-font-sans` 연결. 이 계약 변수를 읽는 곳이 없어 wantedSans가
로드만 되고 어디에도 적용되지 않았다. 이제 @fox 밖 텍스트가 wantedSans를 쓴다.
- next.config.ts: `/fonts/*`를 no-store에서 제외. public/ 자산이라 그대로 두면 페이지를
열 때마다 2.2MB를 다시 받는다.
- proxy.ts: 폰트 확장자를 matcher에서 제외. 세션 없는 방문자의 폰트 요청이 `/login`으로
리다이렉트돼 로그인 화면만 대체 서체로 그려졌다.
- @fox/README.md: "호스트 앱과의 계약"이 @fox 컴포넌트도 `--app-font-sans`를 읽는 것처럼
적혀 있었으나 사실이 아니다. 실제 요구사항(Pretendard @font-face·400/600/800)으로 교체.
FoxCarouselIndicator number형 56.92px → 59.69px. 시안 62px과의 잔여 2.31px은 Figma가 텍스트
상자 폭을 정수로 올리고(+1.57) 마지막 글자의 음수 자간을 빼지 않는(+0.75) 표기 차이다.
Co-Authored-By: Claude Opus 5
Figma Navigation 섹션(391:4035)의 7개 컴포넌트 타입을 5개로 옮겼다.
- FoxBreadcrumb (breadcrumb)
- FoxPagination (pagination + pagination-item)
- FoxCarouselIndicator (carousel-dot + carousel-number)
- FoxCarouselButton (carousel-arrow + carousel-atomic)
- FoxCarouselArea (carousel-area)
합친 근거는 껍데기가 같고 안에 든 것만 다르다는 것이다. 원형 버튼 둘은
테두리·그림자만 달라 type으로, 위치 표시 둘은 흰 알약이 같아 type으로 갈랐다.
pagination의 시안 device 축은 프롭이 아니라 화면 폭이 정한다 — 768px 미만에서
이전·다음이 첫 줄로 빠지고 번호가 아래 줄에 선다. 마크업은 한 벌이고 DOM 순서는
읽는 순서 그대로다.
@fox/core/icons 신설 — 손으로 그리지 않고 Figma export 자산의 path를 옮겼다.
시안이 아이콘을 정사각 박스 안에 여백을 두고 앉히므로 그 여백까지 translate로
재현했다. CaretLeft/Right는 Regular·Bold 두 벌이다(시안이 자리마다 다르게 물렸다).
승인된 비토큰 값: 숫자칸 3.2rem/2.4rem, 캐러셀 점 0.8rem, 활성 막대 2.4rem,
가운뎃점 0.4rem — 모두 시안 값이나 Figma가 변수로 export하지 않는다.
Co-Authored-By: Claude Opus 5
공지사항 등록 시 "A 'use server' file can only export async functions,
found object"로 500이 발생했다. boards/_actions.ts가 INITIAL_* 상태 상수를
함께 export한 것이 원인이다.
관리자 회원에서 같은 원인을 고친 방식(abb6259)에 맞춰 *FormState 타입과
INITIAL_* 상수를 lib/domain/board-post-form.ts로 옮겼다. 빌드·타입체크는
통과하고 폼을 실제로 제출해야만 드러나는 런타임 전용 제약이라, 근거를
domain 파일 주석에 남겼다.
Co-Authored-By: Claude Opus 5
충돌 2건 해결:
- lib/http/backend-fetch.ts: hub 버전 채택. hub가 이미 PUT/DELETE·form·
multipart를 갖췄고 data:null 성공을 canHaveNullData로 다루므로, 같은 목적으로
추가했던 backendCommand를 걷어내고 게시판 Repository를 그 규약에 맞췄다.
파일 업로드용 timeoutMs만 BackendRequestInit에 추가로 남겼다.
- admin-sidebar.tsx: 꾸미기아이템관리(hub)와 게시판관리(고객센터)를 함께 둔다.
Co-Authored-By: Claude Opus 5
사이드바 「게시판관리(고객센터)」 그룹과 3개 화면 신설
(/boards/notices, /boards/inquiries, /boards/faqs).
백엔드 최신화(develop 924db37)로 새로 생긴 관리자 게시판 API에 연동한다.
세 화면이 TB_COM_BBS 한 테이블을 stngId로만 구분하므로 도메인·Repository·
Server Action·공용 컴포넌트를 한 벌로 두고 BoardType으로 분기한다.
- 공지사항: 목록·등록·수정·삭제 (구분/사용여부 필터, 상단고정·노출기간·앱푸쉬)
- 1:1문의: 목록·상세답변·삭제 (등록 없음, 전화번호 마스킹, 진행상태)
- FAQ: 목록·등록·수정·삭제 (구분/유형 필터)
- 첨부파일 업로드(Server Action 경유)와 다운로드 중계 라우트 추가
백엔드 계약 확인에 따른 결정(사용자 확인 완료):
- totalCount·검색조건 한계로 전체를 받아 서버에서 검색·필터·페이징
- stngId·moduleId·구분/유형/진행상태 코드는 백엔드 미확정이라 상수 한 곳에
임시값을 두고 추후 교체(BOARD_SETTING_IDS 등)
- 유형은 저장 필드가 없어 임시 파라미터명으로 전송(백엔드 추가 예정)
- 노출기간·앱푸쉬는 조회 SELECT에 없어 전송만 하고 조회는 빈 값
- 본문은 리치 에디터 대신 글자수 카운트 textarea
backend-fetch: PUT/DELETE·폼 인코딩·멀티파트 지원 추가. 쓰기 API가
success(null)을 반환해 기존 backendFetch로는 성공이 실패로 읽히므로
데이터 없는 쓰기 전용 backendCommand를 분리했다.
Co-Authored-By: Claude Opus 5
두 레인이 같은 시기에 backendFetch에 form-urlencoded 전송을 추가해 lib/http/backend-fetch.ts가
충돌했다. 원인이 같다 — 백엔드의 쓰기 API가 @RequestBody가 아니라 @ParameterObject로 받아
JSON을 보내면 전 필드가 null로 저장된다(관리자 등록·수정, 아이템 등록·수정 모두).
아이템 쪽 구현이 관리자 쪽을 포함하므로 그것을 채택했다:
- method에 DELETE가 더 있다(아이템 삭제).
- form 값이 string 외에 number·undefined를 받는다(undefined는 전송에서 제외).
- multipart 본문을 지원한다(아이템 이미지 업로드).
- 본문·Content-Type 결정을 buildRequestBody 한 곳으로 모아 세 형식을 한눈에 볼 수 있다.
관리자 레인의 호출부는 Record을 넘기므로 넓어진 타입에 그대로 들어맞는다.
주석에는 두 도메인의 예시를 함께 남겼다.
백엔드(develop 924db37)에 관리자 쓰기 API가 추가되어 mock을 걷어낸다.
등록 POST /mngr/admin, 수정 PUT /mngr/admin, 중복확인과 단건 조회는 전용 GET을
쓴다. mock 저장소에는 삭제만 남는다 — 백엔드에 삭제 엔드포인트가 없고, 수정
API로도 USE_YN을 끌 수 없어 비활성화로 대신할 수 없다.
수정 시 비밀번호를 필수로 막는다. 백엔드 UPDATE가 LOGIN_PW를 조건 없이
덮어써서 빈 값을 보내면 그 계정이 로그인 불가가 되기 때문이다.
메뉴 선택은 시안대로 유지하되 전송하지 않는다 — 관리자별 메뉴 권한 개념이
백엔드에 없다.
Co-Authored-By: Claude Opus 5
mock 저장소를 제거하고 /api/v1/mngr/item CRUD와 파일 업로드 API에 연결한다. 기존 구현은
"이 도메인에는 백엔드 API가 전혀 없다"는 전제로 만들어져 있었으나, 백엔드에 등록·수정·삭제까지
갖춘 API가 존재해 스키마에 맞춰 도메인 타입부터 다시 맞췄다.
- 아이템ID는 사용자 입력이 아니라 백엔드 자동 채번(itemSn)이다. 시안도 "등록 후 자동발급
(Read Only)"이라 등록 폼의 입력 필드를 없애고 목록·수정 팝업에는 itemSn을 그대로 노출한다.
- 유형은 개별=N, 셋트=S로 매핑한다. 목록 조회는 searchItemType이 필수라 값이 없으면 아무것도
조회되지 않는다.
- 카테고리는 공통코드가 정비되기 전까지 프론트 임시 코드로 개발한다(사용자 지시). 표기는
백엔드가 조인해 준 이름을 우선 쓰고 없으면 임시 목록에서 찾는다.
- 이미지는 파일 하나만 받아 atchFileId에만 저장한다(썸네일은 추후 백엔드 자동생성 예정).
브라우저가 백엔드에 직접 올리지 않도록 Server Action이 File을 받아 중계한다. 목록 썸네일은
인증이 필요 없는 이미지 GET 주소를 서버에서 만들어 내려준다.
- 총건수 보정은 학생 목록과 동일하다(백엔드 PaginationUtil에 count 쿼리가 없다).
lib/http/backend-fetch.ts에 PUT/DELETE와 form·multipart 본문을 추가했다. 아이템 쓰기 API는
@RequestBody가 아니라 @ParameterObject로 받으므로 JSON을 보내면 전 필드가 null인 채 저장된다.
FoxInput·TextArea·PhoneNumber·Certified·Email·Address·FileUpload가 라벨·
헬퍼·입력 상자·상태 규칙을 같은 값으로 되풀이하고 있었다. 시안에서 이들이 모두
같은 공용 컴포넌트라 값이 갈라질 이유가 없다.
- @fox/styles/_form-field.scss 추가 — root·label·message·message-icon·
box·box-size·field·auto-states·fixed-states
- 믹스인만 있어 @use 해도 CSS가 늘지 않는다(파티셜 단독·묶음 모두 확인)
- 컴포넌트마다 다른 것만 인자로: 상자 gap·교차정렬, 알맹이 글자 크기·줄높이,
알맹이 element 이름(field/segment), 오류 판정 범위
- PhoneNumber unit은 조각이 다른 컴포넌트라 헬퍼 오류를 넓게 본다 —
$invalid-within으로 그대로 유지
값은 하나도 바꾸지 않았다. 컴파일 결과를 규칙 단위로 대조해 304개 규칙의
선택자·선언·순서가 모두 동일함을 확인했다(선언 순서만 5개 규칙에서 다르며
서로 다른 속성이라 렌더링 동일).
Co-Authored-By: Claude Opus 5
세로 배치의 교차정렬이 기본값 stretch라 버튼이 오른쪽 칸 폭(567px)만큼
늘어났다. 시안(txt-area)은 items-start이고 버튼은 shrink-0이다.
- align-items: flex-start 추가 — 버튼이 글자만큼만 차지한다
- 설명에 inline-size: 100% — 시안 min-w-full대로 폭을 채운다
Co-Authored-By: Claude Opus 5
`로 그리면서 브라우저 기본값을 지우지 않아 왼쪽에 40px
(padding-inline-start)과 위아래 10px(margin-block)이 붙었다. 우리 SCSS에는
`__list` 패딩 규칙이 없었고 전부 UA 스타일이었다.
같은 자리를 쓰는 FoxSelectOption은 초기화가 되어 있었다 — 이 파일만 빠져 있었다.
Co-Authored-By: Claude Opus 5
Figma 시안 다섯을 한 컴포넌트로 옮긴다 — file-upload(391:3677) ·
file-upload-area(392:5968) · file-upload-img(391:3732) · file-list(392:5938) ·
file-list-item(391:3509). 고르는 방식만 다르고 목록은 같아서다.
시안에서 버튼·입력이 모두 기존 컴포넌트의 인스턴스라 그대로 조합한다.
썸네일 삭제 버튼은 FoxIconButton overlay xsm이 시안과 정확히 같다(24px ·
모서리 4 · 검정 50% · 배경흐림 10 · 흰 아이콘).
업로드는 하지 않는다. 파일을 고르면 원본 File을 넘길 뿐이고 진행률·서버
오류를 목록에 어떻게 비출지는 files로 정한다. files를 안 주면 안에서 들고
있어 간단한 폼에 그대로 쓴다.
default 모드는 시안의 두 상태를 모두 갖는다 — 비었으면 흰 칸에
파일선택(secondary), 파일 하나를 목록 없이 들고 있으면 칸이 회색으로 잠기고
버튼이 삭제(default 계열 · 휴지통)로 바뀐다. 흰 칸 규칙은 FoxInput의 읽기
전용 규칙(0,6,0)보다 특이도를 높여 로드 순서와 무관하게 이기도록 적었다.
끌어다 놓기는 prop으로 켜되 area는 안내문이 그렇게 말하므로 언제나 받는다.
입력칸 폭과 썸네일 크기는 토큰에 없어 prop 기본값으로 뒀다(사용자 승인).
Co-Authored-By: Claude Opus 5
Figma form-email(136:3092)과 form-address(5346:5823)를 옮긴다. 두 시안 모두
상자가 input·select 인스턴스이고 버튼도 btn 인스턴스라 FoxInput·FoxSelect·
FoxButton을 그대로 조합했다 — 두 SCSS는 배치와 `@` 구분자만 갖는다.
FoxEmail
값은 아이디@도메인이 합쳐진 문자열 하나다. 도메인을 목록에서 고르면 옆 칸이
그 값으로 덮이고 읽기 전용이 되며, "직접입력"을 고르면 잠금만 풀린다.
확인 버튼은 onVerify를 넘겼을 때만 렌더된다.
칸은 시안의 240px을 최소폭으로 두고 남는 폭을 나눠 갖는다 — 좁아지면 줄이
넘어간다(사용자 승인). 토큰 스케일에 240이 없어 이 한 줄만 리터럴이다.
FoxAddress
우편번호와 주소는 검색 결과로만 채워지는 읽기 전용이고 상세주소만 입력한다.
어떤 우편번호 서비스를 쓰는지 @fox는 모른다 — 호출부가 onSearch에서
FoxAddressSearchResult(zipCode·address·선택 detail)로 바꿔 돌려주고, 취소는
null이다. detail을 안 넘기면 사용자가 적어 둔 상세주소를 건드리지 않는다.
Co-Authored-By: Claude Opus 5
Figma form-certified(190:2017)의 세 줄을 옮긴다. 전화번호는 FoxPhoneNumber
(combine), 두 버튼은 FoxButton(secondary·primary 전체폭)을 그대로 쓴다 —
시안도 그 인스턴스다. 인증번호 상자만 자체로 그리는데, 오른쪽 남은 시간이
FoxInput의 아이콘 슬롯(정사각 20px)보다 넓기 때문이다.
보내기·확인은 호출부가 Promise로 넘긴다. resolve면 성공, throw·reject면
실패로 보고 이벤트를 올린다 — onSendSuccess/onSendFail/onVerifySuccess/
onVerifyFail/onExpire.
화면은 최소한만 반응한다. 보내기가 성공해야 인증번호 칸과 확인 버튼이 열리고,
인증에 성공하면 전화번호·인증번호·두 버튼이 전부 잠긴다. 실패 문구는 호출부가
보여준다.
남은 시간은 remainingSeconds를 주면 그 값을 그리고, 없으면 expiresIn부터
컴포넌트가 센다. 0에 닿는 순간 onExpire를 한 번만 올린다.
Co-Authored-By: Claude Opus 5
칸에 들어오는 값에서 숫자가 아닌 글자를 걸러낸 뒤 자릿수를 자른다. 붙여넣기로
하이픈·공백이 섞여 와도 걸리고, 한 칸에 `010-1234`를 붙여도 넘치지 않는다.
밖에서 받은 value도 같은 방식으로 읽는다 — `010-1234-5678`처럼 꾸며진 값을
넣어도 칸이 맞게 갈리고, 내보낼 때는 숫자만 남는다.
Co-Authored-By: Claude Opus 5
Figma form-phonenumber(391:3156)의 두 모양을 옮긴다. unit은 상자 셋을
하이픈으로 잇고, combine은 상자 하나에 세 칸을 둔다.
값은 숫자만 담긴 문자열 하나다 — 하이픈은 화면에만 있고 값에는 없다. 화면의
세 칸이 진실 공급원이라 입력 도중 "0101"처럼 어디까지가 앞자리인지 알 수 없는
값이 생겨도 칸이 흔들리지 않고, 밖에서 value를 바꿨을 때만 다시 나눈다.
나눌 때 앞자리는 prefixOptions 중 가장 긴 일치를, 뒷자리는 항상 마지막 네
자리를 쓴다 — 010-123-4567과 010-1234-5678이 둘 다 맞게 갈린다. 목록이 없으면
maxLengths[0]만큼을 앞자리로 보므로 지역번호 02는 목록에 넣어야 한다.
unit의 조각은 시안에서도 select·input 인스턴스라 FoxSelect·FoxInput을 그대로
조합한다. 상태·포커스가 저절로 따라오고 이 파일은 줄 배치와 하이픈만 갖는다.
combine 상자만 자체 규칙을 둔다.
칸을 다 채우면 다음 칸으로 옮기고 빈 칸에서 지우면 앞칸으로 돌아간다
(autoAdvance로 끌 수 있다).
Co-Authored-By: Claude Opus 5
FoxTextArea와 별도로 들어온 FoxSelect 계열이 등록 목록 세 곳에서 부딪쳤다.
셋 다 추가만 하는 목록이라 양쪽을 합쳤다.
components.scss의 select 세 줄은 나머지와 같은 상대 경로 표기로 맞췄다 —
같은 폴더의 파티셜이라 결과는 같다.
component-registry.tsx의 FoxInput 임포트는 위쪽 배럴 임포트와 겹쳐 뺐다.
Figma textarea(135:1655)의 6상태를 옮긴다. 시안에 크기 축이 없어 상자는
하나뿐이고 높이는 rows가 정한다(기본 5줄, 시안과 같음).
상태 판정은 FoxInput과 같은 두 갈래다 — 기본은 브라우저가 판단하고(포커스·
값·네이티브 속성·aria-invalid), data-state를 주면 그 모양으로 고정된다.
상태 매트릭스도 FoxInput과 동일해 규칙을 그대로 옮겼다.
하단은 왼쪽 헬퍼와 오른쪽 글자수 카운터로 나뉜다. 카운터는 현재 길이만 굵고
색이 다르며, 오류일 때 빨개진다(시안의 error 변형이 100/100을 빨갛게 둔다).
maxLength가 없으면 개수만 적는다. 비제어 입력의 길이는 직접 따라간다.
리사이즈는 시안에 신호가 없어 폭이 흔들리지 않게 세로만 허용한다.
Co-Authored-By: Claude Opus 5
