ADR-0006: Spartan helm 컴포넌트의 자유로운 수정을 허용한다
상태
Accepted
날짜
2026-08-10
맥락
UI 킷으로 Spartan을 채택했습니다. Spartan은 두 층으로 구성됩니다. @spartan-ng/brain은 접근성과 동작을 담당하는 헤드리스 프리미티브이며 npm 의존성입니다. helm은 스타일 층이며 CLI로 소스를 복사해 프로젝트가 소유합니다.
복사해 온 helm 소스를 어디까지 수정할 수 있게 할지 정해야 합니다. 사본이므로 수정할수록 업스트림 개선을 받기 어려워집니다.
초기에는 "토큰과 클래스만 수정하고 마크업 구조와 API는 원본 유지"를 검토했습니다. 대부분의 커스터마이징이 스타일이므로 제약이 크지 않고, 업스트림을 다시 받아 비교하기 쉽기 때문입니다.
이 방안이 성립하지 않는 요구사항이 확인되었습니다. 적응형 UI입니다. 같은 논리적 컴포넌트가 상호작용 특성에 따라 다른 DOM과 다른 상호작용 모델을 가져야 합니다. 셀렉트가 포인터 환경에서는 앵커 드롭다운이고 터치 환경에서는 바텀시트여야 하는 식입니다. 이는 클래스 교체로 표현되지 않으며 구조 변경이 필수입니다.
결정
shared/ui/로 복사한 helm 컴포넌트의 마크업 구조, 클래스, 입출력 API를 모두 자유롭게 수정합니다.
단, brain 디렉티브 연결은 유지합니다. 마크업 정리 과정에서 디렉티브를 제거하는 것을 금지합니다.
세부 규칙은 디자인 시스템과 토큰이 원본입니다.
검토한 대안
토큰과 클래스만 수정, 구조와 API는 원본 유지
| 구분 | 내용 |
|---|---|
| 장점 | 업스트림을 다시 받아 비교하기 쉽습니다. 사본이 낡는 속도가 느립니다 |
| 단점 | 구조 변경이 필요한 요구사항을 수용할 수 없습니다 |
| 기각 사유 | 적응형 UI가 DOM 구조 자체를 바꾸는 일이므로 이 제약 아래에서는 구현이 불가능합니다 |
원본을 그대로 두고 감싸는 래퍼 작성
| 구분 | 내용 |
|---|---|
| 장점 | 업스트림 갱신이 덮어쓰기로 끝나 가장 깨끗합니다 |
| 단점 | 버튼 색 하나를 바꾸려 해도 파일이 하나 늘어납니다. shared/ui에 원본과 래퍼가 쌍으로 쌓여 탐색 비용이 증가합니다 |
| 기각 사유 | 적응형 구현에서 래퍼가 원본의 DOM을 바꿀 수 없으므로 결국 원본을 고쳐야 합니다. 래퍼 계층은 비용만 남습니다 |
결과
적응형 UI를 구현할 수 있습니다. 시각적 요구사항을 제약 없이 반영할 수 있습니다. 서드파티 유지보수가 중단되어도 helm 코드는 우리 것이므로 계속 사용할 수 있습니다.
감수하는 사항은 다음과 같습니다.
- 업스트림의 시각적 개선이 자동으로 반영되지 않습니다. Spartan이 helm의 마크업을 개선해도 우리 사본에는 오지 않습니다. 다만 갱신을 완전히 포기하는 것은 아니며,
@spartan-ng/cli:healthcheck --autoFix가 업그레이드 후 폐기된 API를 조정해 줍니다. - helm 코드의 결함은 우리 책임입니다. 취약점이 발견되어도 패키지 갱신으로 해결되지 않습니다.
개정
- 2026-08-11: 업스트림 갱신 수단이 존재함을 확인했습니다.
@spartan-ng/cli:healthcheck --autoFix가 Spartan 업그레이드 후 폐기된 API를 조정합니다. "실질적으로 갱신을 포기하는 결정"이라는 서술이 과했으므로 완화했습니다. 결정 자체는 바뀌지 않습니다.
두 번째 대가가 감당 가능한 이유는 층이 분리되어 있기 때문입니다. 접근성과 동작은 brain이 소유하며 helm은 시각 층입니다. helm을 고쳐도 포커스 트랩, 키보드 조작, ARIA 연결은 brain이 계속 담당합니다. 사본이 낡아서 잃는 것은 시각적 개선이지 접근성이 아닙니다.
이 분리가 성립하려면 brain 디렉티브가 유지되어야 하므로, 그 항목만 금지 규칙으로 남깁니다. 디렉티브를 떼어내면 접근성이 함께 사라지는데 이는 화면상으로 드러나지 않아 발견이 늦습니다.