[전수조사/K] 문서: 과장된 주장, 틀린 예제, 결정 사항 반영 #693

문서가 실제 동작과 다르거나 빠진 부분입니다. README의 "Complete CSS-in-JS Syntax Coverage" 같은 과장된 문구는 이번에 한계를 반영해 고칩니다.

전체 계획과 결정 사항은 추적 이슈(#682)에 있습니다. 조사 기준 커밋: 77daad74 (현재 main d0b84255).

결정에 따른 작업

• (필수) "스타일 덮어쓰기 규칙": 보장되는 조합 / CSS 특성상 보장되지 않는 조합(props로 받은 className, 외부 class, 런타임 조립 문자열) / 권장 패턴(prop, variant, styled() 확장). 마이그레이션 문서에도 안내
• (필수) 브라우저 하한: Baseline 2024 명시(light-dark(), @layer, :is())
• (필수) css prop: 사용자 컴포넌트의 동적 값은 style도 전달해야 함
• (권장) Tailwind: devup 기준 breakpoint(theme.breakpoints), Tailwind 이름과 같은 class의 변환 규칙, 지원 범위
• (권장) 런타임 전용 API(D10) 처리 방식
• (필수) 새로 생기는 빌드 에러 목록과 해결 방법

발견 항목

심각도: P0 = 흔한 사용에서 조용히 틀리거나 크래시, P1 = 흔한 패턴이 명시적 에러로 막히거나 드물게 조용히 틀림, P2 = 드문 경우·도구/문서 불일치, P3 = 있으면 좋음.

필수 (2)

• DOC-01 (P1, MISMATCH) Absolute “complete/every syntax” claims contradict known limitations
  • 근거: README.md:44, features/page.mdx and package copies versus COMMON KNOWN-1–15
  • 수정 방향: replace absolutes with a tested support/limitation matrix
• DOC-10 (P1, MISMATCH) Styled-components/Emotion page overclaims full compatibility
  • 근거: COMMON KNOWN-2/3/4/7/8/11/13
  • 수정 방향: add supported-shape and limitation table

권장 (15)

• DOC-02 (P0, WRONG) Button documentation turns a function handler into a string attribute
  • 근거: api-agent/ex008_button.out.txt contains onClick="alert('clicked!!')"
  • 수정 방향: correct shown output and document handler preservation
• DOC-03 (P1, WRONG) Optimization page promises reductions not emitted
  • 근거: concept-agent/all-doc-examples.tsx keeps margin:0 0 0 0 and 16.0000px
  • 수정 방향: update examples or implementation
• DOC-04 (P1, WRONG) RGBA shortest-output example is false
  • 근거: rgba(255,0,0,.5) emitted #FF000080, not #f000
  • 수정 방향: show actual output or safely implement shortening
• DOC-06 (P1, MISMATCH) Legacy theme-integration page uses obsolete schema/type glob
  • 근거: legacy page has colors.primary and df/*.ts; current theme uses variant map and theme.d.ts
  • 수정 방향: remove legacy page or update to variant schema, .d.ts and configurable distDir
• DOC-09 (P1, ERR-gap) Vanilla-extract ordinary-module composition is overclaimed
  • 근거: migration-agent/case-058.ts and case-059.ts error on vars.colors.bg/vars.space
  • 수정 방향: narrow supported forms and document errors, or support deterministic imports
• DOC-11 (P1, MISMATCH) Root translations contain different benchmarks and caveats
  • 근거: README run 33254030962 vs Korean 33239265133; Korean omits fixture caveat
  • 수정 방향: synchronize and date benchmark data
• DOC-13 (P1, MISMATCH) Extractor README output is obsolete
  • 근거: README uses dp1/dp-3/dp-v and Box; readme-agent/01 emits base-37/native element
  • 수정 방향: replace with current probe output
• DOC-14 (P1, MISMATCH) WASM README is unrelated template
  • 근거: bindings README describes wasm-pack-template, unlike package AGENTS/API
  • 수정 방향: replace template
• DOC-17 (P1, MAINT) ESLint package README is empty
  • 근거: zero-byte/empty package README despite seven rules/config export
  • 수정 방향: add package README
• DOC-18 (P1, ERR-gap) ESLint static-value README overstates constants accepted by build
  • 근거: eslint-agent/probe_static.tsx: css() cannot use U at build time
  • 수정 방향: align lint/docs with extractor or narrow claim
• FN-03 (P1, MISMATCH) Feature docs spread a class-name string as component props
  • 근거: apps/landing/src/app/(detail)/docs/features/page.mdx:227-234 shows const cardStyles = css(...) followed by <Box {...cardStyles} />; the API page says css returns a string at docs/api/css/page.mdx:11, and the probe returns a string
  • 수정 방향: change the feature example to <Box className={cardStyles} styleOrder={...}> (or a style-object example if spreading was intended)
• CSS-09 (P2, MISMATCH) Published responsive breakpoint table disagrees with emitted defaults
  • 근거: cascade.tsx emits slot 3 at min-width:992px and slot 5 at 1600px; typography docs list 1024px and 1640px (apps/landing/src/app/(detail)/docs/devup/typography/page.mdx:178-185). Other observed defaults are 480/768/1280 as documented.
  • 수정 방향: Decide which sequence is canonical, then update either default constants or all public breakpoint docs/examples and lock the table with a docs-facing test.
• CSS-10 (P2, MISMATCH) Two-theme color output has no fallback for pre-Baseline-2024 browsers
  • 근거: Shared two-theme colors emit only --primary:light-dark(#F00,#00F). There is no preceding plain fallback or per-theme override. MDN marks light-dark() Baseline 2024 / available across latest browsers since May 2024, and notes older browsers may not support it. Current Chromium accepts it.
  • 수정 방향: Publish an explicit browser-support floor. If older browsers are supported, emit a plain default variable first and a guarded light-dark() override, or always use per-data-theme variables.
• FN-10 (P2, MISMATCH) styled(makeStyles()) behavior contradicts its explicit documentation
  • 근거: styled.div(makeStyles()) compiles to a red class in styled-dynamic.tsx; docs say “A whole style object computed that way (css(makeStyles()), styled.div(makeStyles())) is a build error” at docs/features/page.mdx:238
  • 수정 방향: decide the contract, then either reject whole computed objects consistently or update docs and add exact/uncertain function-result tests
• JSX-11 (P2, MISMATCH) Selector documentation is materially narrower than the public type surface
  • 근거: types generate group forms for every simple/advanced selector and support direct @media .../@supports .../@container ... plus record forms (packages/react/src/types/props/selector/index.ts:34-58,91-107); docs list only four group selectors and headline only underscore at-rules (apps/landing/src/app/(detail)/docs/api/group-selector/page.mdx:43-84, api/selector/page.md…
  • 수정 방향: generate selector reference tables from the type/source unions and document advanced params, generated group keys, pseudo-elements, styleOrder, and every at-rule spelling.

선택 (16)

• DOC-05 (P2, MISMATCH) N/M-base alphabet/count documentation is wrong
  • 근거: num_to_nm_base.rs has a-z plus _ as 27 single-character names and digits in continuation
  • 수정 방향: document exact alphabets/order and 27 count
• DOC-07 (P2, MISMATCH) Generated declaration path is presented as fixed
  • 근거: plugin source joins configurable distDir with theme.d.ts
  • 수정 방향: state default and configurable path
• DOC-08 (P2, MISMATCH) Figma documentation links two different plugin IDs
  • 근거: legacy ID 1412341601954480694 vs current ID 1446848873498976065
  • 수정 방향: verify live listing and consolidate
• DOC-12 (P2, PERF) “Latest” benchmarks/version are stale
  • 근거: docs say 1.0.40/former lite evaluator; probe banner is 1.0.81/current Boa
  • 수정 방향: label historical or rerun
• DOC-15 (P2, MISMATCH) Components README documents the wrong package
  • 근거: packages/components README installs/describes @devup-ui/react
  • 수정 방향: rewrite package-specific README
• DOC-16 (P2, MISMATCH) reset-css README omits its actual API
  • 근거: generic copied extractor content; no resetCss usage/scope/import
  • 수정 방향: rewrite README
• DOC-19 (P2, MISMATCH) style-order-range examples misstate scope and strings
  • 근거: bare divs are ignored; parseInt accepts 100abc
  • 수정 방향: import devup component and document/ tighten parsing
• DOC-20 (P2, MISMATCH) Rule READMEs omit recommended-config diagnostic overlap
  • 근거: duplicate “valid” [1,null,null] triggers no-useless-tailing-nulls
  • 수정 방향: label per-rule examples or show combined diagnostics
• DOC-21 (P2, MAINT) Package Korean README links are broken
  • 근거: package READMEs link sibling README_ko.md; none exist
  • 수정 방향: add files or remove links
• DOC-22 (P2, MISMATCH) Fixed class names are shown as stable output
  • 근거: package docs show d0/d1 while probe emits a/b/c and prefix/state are configurable
  • 수정 방향: mark names implementation-dependent or use debug names
• DOC-23 (P2, MAINT) KNOWN-18 and root AGENTS metadata are stale
  • 근거: libs/AGENTS says Oxc 0.106; Cargo.lock 0.151; root says old commit/main/9,094 extractor lines
  • 수정 방향: regenerate all AGENTS metadata
• DOC-24 (P2, TEST) Group-selector and selector tables lack reproducible exact evidence
  • 근거: extracted group fragments did not reproduce documented :is rule; selector aliases not individually tested
  • 수정 방향: add generated matrix tests and paste exact output
• DOC-25 (P2, TEST) Style-props mapping table has no exhaustive conformance fixture
  • 근거: 200+ mappings are prose-only; representative unit cases pass
  • 수정 방향: generate table-driven doc test
• DOC-26 (P2, MAINT) Migration examples include parser-invalid standalone fragments
  • 근거: migration-agent/case-016.tsx and case-026.tsx panic parser after mechanical extraction
  • 수정 방향: make examples standalone or mark partial snippets
• DOC-27 (P2, MISMATCH) _first selector maps to nonstandard :first in docs
  • 근거: selector/page.mdx lines 71–78
  • 수정 방향: confirm intended :first-child/:first-of-type and correct
• DOC-28 (P2, MAINT) Figma behavioral claims have no source or local verification path
  • 근거: external plugin absent; two stale/conflicting pages
  • 수정 방향: consolidate, date and link authoritative plugin docs