[전수조사] 결과와 개발 범위 (2026-09-30)

[owjs3901]

devup-ui 저장소 전체를 전수조사한 결과와 확정된 개발 범위입니다. 조사 기준 커밋은 77daad74(#681 병합 직전)이고, 작업은 main(d0b84255)에서 작업 묶음별 PR로 진행합니다.

조사 방식

• 13개 영역을 병렬로 조사했습니다: styled-components, Emotion, vanilla-extract/StyleX, Tailwind, devup 컴포넌트·props, 스타일 함수·빌드 타임 값, CSS·theme, vite/webpack/rsbuild/bun 플러그인, next 플러그인·벤치마크, ESLint·타입, 문서, 테스트·CI·결정성·성능, 런타임 패키지.
• 영역마다 공식 문서의 public API와 소스의 export·옵션으로 기준 목록을 먼저 만들었습니다. 그다음 모든 칸을 플러그인과 같은 WASM 경로로 실행해 분류했습니다: 정상 / 명시적 빌드 에러 / 조용히 틀림 / 런타임 크래시 / 비결정적.
• 결과는 261건입니다(P0 50, P1 131, P2 70, P3 10). P0와 주요 P1 19건은 다시 재현해 확인했습니다. 재현 결과로 심각도 3건을 조정하고(INF-06, INF-11, FN-04), 새 항목 1건(NEW-01)을 추가했습니다.

확정된 원칙과 결정

• 런타임 추가는 절대 허용하지 않습니다. 빌드 타임에 알 수 없는 것은 문서화하거나 빌드 에러로 처리합니다.
• 조합 우선순위: 한 곳에서 조합하는 경우는 빌드 타임에 뒤가 이기게 합니다(css()/cx(), styled() 확장, attrs, vanilla-extract, StyleX, spread). 다른 파일과 include 라이브러리의 정의도 읽어서 합칩니다.
  • props로 받은 className, CSS Modules 같은 외부 class, 런타임에 조립되는 문자열은 CSS 자체의 특성으로 문서화합니다.
• Tailwind: 기본으로 켜 두고, 알아보지 못한 토큰과 variant는 원문 그대로 둡니다(보존형).
  • v4 최신을 따르고, 플러그인 class만 제외합니다.
  • breakpoint는 devup 기준입니다(devup.json theme.breakpoints).
  • dark:는 devup theme을 따릅니다.
  • devup.json theme 값(bg-primary 등)과 Tailwind 원래 방식(CSS @theme, 기본 팔레트)을 모두 지원합니다.
• compat theme: useTheme/withTheme은 실제 theme 객체를 context로 제공합니다.
• React: 18과 19를 모두 지원합니다(peer ^18 || ^19).
• 호환 기준 버전: 최신입니다. styled-components v6, Emotion 11, StyleX·vanilla-extract 최신, Tailwind v4. v5 전용 API는 비용이 작으면 지원합니다.
• Emotion 배열 값: alias된 Emotion 파일에서는 fallback 의미입니다.
• prop 전달(런타임 없음)
  • 스타일 함수가 읽는 prop은 DOM에 넘기지 않습니다. 단 태그의 유효한 속성이면 넘깁니다.
  • $ prop은 넘기지 않습니다.
  • shouldForwardProp은 빌드 타임에 계산합니다.
  • spread로 들어오는 모르는 prop은 그대로 넘기고 문서화합니다.
• 브라우저 하한: Baseline 2024를 문서에 명시합니다.
• css prop 동적 값: 사용자 컴포넌트는 style도 넘겨야 한다고 문서화합니다.
• 결정성: 빌드 시작 시 모든 파일을 경로 순으로 먼저 훑어 번호를 확정합니다(측정: devup 파일 1,000개당 약 0.2~1초).
• 다크 theme 판정: 이름이 dark인 theme만 다크로 봅니다. 다른 이름은 devup.json에서 지정합니다.
• 런타임 전용 API: 결과에 영향이 없는 API는 아무 일도 하지 않는 호환 구현으로 통과시킵니다. stylis 플러그인은 빌드 에러로 처리하고 대안을 안내합니다.

새로 생기는 빌드 에러

기존에 빌드되던 코드가 새로 빌드 에러가 되는 경우입니다. 모든 에러는 파일:줄:열, 해당 코드, 원인, 고치는 방법을 함께 표시합니다. changepack(Patch)에도 발생 조건을 적습니다.

• 빌드 타임에 계산할 수 없는 shouldForwardProp(props 값이나 런타임 값을 참조하는 함수)
• StyleSheetManager/createCache에 넘긴 stylis 플러그인(CSS 결과를 바꾸므로). 대안: logical property(marginInlineStart 등)
• 유효하지 않은 selector 키(selectors 등, TOOL-06)
• 지금은 조용히 런타임으로 빠지거나 누락되는 compat API 중 지원하지 못하는 것(예: StyleX marker API, vanilla-extract 동반 패키지 중 미지원 기능)
• namespace/default import 멤버를 값으로 읽는 코드 중 컴파일할 수 없는 것(Devup.css를 변수에 담아 넘기는 경우 등)

진행 순서 (작업 묶음별 PR, 모두 main에서 분기)

1. 빠른 수정: 테스트 격리 #[serial](L), lint autofix 범위와 오탐(J)
2. CSS 생성 정확성(E 필수)과 플러그인 P0(H: PLG-01~04)
3. Tailwind 보존형(B 필수)
4. 조합 우선순위(A)
5. compat과 흡수 라이브러리(C·D 필수): as, prop 전달, theme 계약, 크래시, css prop, 컴포넌트 선택자, @emotion/css, 배열 fallback
6. React 18·19(M)와 React 18 fixture
7. UI kit 접근성 P0(I)
8. 문서(K 필수): README 주장, 스타일 덮어쓰기 규칙, 브라우저 하한 등. 동작이 바뀌는 PR은 해당 문서를 함께 고칩니다.
9. 권장 범위: 결정성(G), 플러그인 P1(H), 추출 의미론(F), Tailwind v4 추종(B), 타입·lint(J), 테스트 인프라(L), 나머지 문서(K)

작업 묶음

• [전수조사/L] 테스트·CI·보안·성능 #683 L 테스트·CI·보안·성능 (21건: 필수 1, 권장 7, 선택 13, 제외 0)
• [전수조사/J] 타입·ESLint 정합성 #684 J 타입·ESLint 정합성 (24건: 필수 2, 권장 18, 선택 4, 제외 0)
• [전수조사/E] CSS 생성 정확성: 순서, layer, theme, 유효하지 않은 CSS #685 E CSS 생성 정확성: 순서, layer, theme, 유효하지 않은 CSS (19건: 필수 15, 권장 1, 선택 3, 제외 0)
• [전수조사/H] 빌드 플러그인·WASM 바인딩 #686 H 빌드 플러그인·WASM 바인딩 (41건: 필수 4, 권장 26, 선택 11, 제외 0)
• [전수조사/B] Tailwind className: 보존형 동작과 v4 추종 #687 B Tailwind className: 보존형 동작과 v4 추종 (18건: 필수 6, 권장 11, 선택 1, 제외 0)
• [전수조사/A] 조합 우선순위: 뒤에 쓴 스타일이 이기게 (빌드 타임 정적 해결) #688 A 조합 우선순위: 뒤에 쓴 스타일이 이기게 (빌드 타임 정적 해결) (10건: 필수 10, 권장 0, 선택 0, 제외 0)
• [전수조사/C] styled/compat 런타임 계약: as, prop 전달, theme, 크래시 #689 C styled/compat 런타임 계약: as, prop 전달, theme, 크래시 (23건: 필수 14, 권장 7, 선택 2, 제외 0)
• [전수조사/D] 흡수 라이브러리 기능: css prop, 컴포넌트 선택자, @emotion/css, VE·StyleX API #690 D 흡수 라이브러리 기능: css prop, 컴포넌트 선택자, @emotion/css, VE·StyleX API (25건: 필수 7, 권장 12, 선택 3, 제외 3)
• [전수조사/M] React 18·19 지원과 패키지 메타데이터 #691 M React 18·19 지원과 패키지 메타데이터 (6건: 필수 5, 권장 1, 선택 0, 제외 0)
• [전수조사/I] UI kit(@devup-ui/components)·theme 런타임·reset-css #692 I UI kit(@devup-ui/components)·theme 런타임·reset-css (19건: 필수 4, 권장 15, 선택 0, 제외 0)
• [전수조사/K] 문서: 과장된 주장, 틀린 예제, 결정 사항 반영 #693 K 문서: 과장된 주장, 틀린 예제, 결정 사항 반영 (33건: 필수 2, 권장 15, 선택 16, 제외 0)
• [전수조사/G] 결정성: 같은 소스는 항상 같은 출력 (파일·class 번호) #694 G 결정성: 같은 소스는 항상 같은 출력 (파일·class 번호) (14건: 필수 0, 권장 14, 선택 0, 제외 0)
• [전수조사/F] devup 추출 의미론: spread, 섀도잉, 배럴 re-export, 모듈 간 값 #695 F devup 추출 의미론: spread, 섀도잉, 배럴 re-export, 모듈 간 값 (8건: 필수 0, 권장 7, 선택 1, 제외 0)

미지수 (확인하지 못한 것과 확인 방법)

• Firefox·WebKit에서 CSS를 검증하지 않았습니다(Chromium과 명세만). → 브라우저 매트릭스 fixture
• 실제 번들러 end-to-end를 돌리지 않았습니다(next dev/build, App/Pages router, RSC, HMR, standalone, Edge, Vite 다중 environment, 라우트 청크 간 CSS 순서). → 최소 fixture 앱 + 브라우저 단언
• React 18 실행, 스크린리더, CSP 차단을 실제로 확인하지 않았습니다. → React 18 fixture, 보조기기 수동 확인, CSP 헤더 fixture
• 멀티 워커 결정성을 스트레스 테스트하지 않았습니다. → 순서를 섞은 반복 추출 테스트
• SemanticBuilder 단독 비용과 WASM 크기 추이를 모릅니다. → 단계별 타이머, 과거 npm tarball 비교
• 계산된 값으로 치환된 부분의 source map 정확도를 모릅니다. → source-map consumer 단언
• 모듈 해석 중 package exports와 tsconfig paths 경로를 확인하지 못했습니다. → 플러그인 resolver 통합 fixture
• 배포 tarball의 workspace:^ 치환을 관찰하지 않았습니다. → pack 결과 검사
• Emotion jsxDEV(dev runtime)와 @emotion/babel-plugin 출력 형태를 확인하지 못했습니다. → dev 설정으로 컴파일한 fixture
• StyleX·vanilla-extract 버전별 차이(unitless 표, attrs 반환형, RecipeVariants 타입)를 확인하지 못했습니다. → 최신 버전 고정 + 공식 타입 테스트
• 문서의 200개 이상 style-prop 매핑과 selector alias를 개별 확인하지 않았습니다. → 표 기반 doc 테스트
• autofix의 주석 보존과 동적 styleOrder의 실제 순서를 확인하지 못했습니다. → RuleTester 케이스, 브라우저 순서 단언