Skip to content

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

Closed

Description

@owjs3901

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

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

결정에 따른 작업

  • (필수) "스타일 덮어쓰기 규칙": 보장되는 조합 / CSS 특성상 보장되지 않는 조합(props로 받은 className, 외부 class, 런타임 조립 문자열) / 권장 패턴(prop, variant, styled() 확장). 마이그레이션 문서에도 안내 — docs(migration): say which style wins and list every default alias #995 (docs/migration "Which style wins")
  • (필수) 브라우저 하한: 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 — docs(landing): correct remaining audit mismatches #909
    • 근거: 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 — docs(landing): correct remaining audit mismatches #909
    • 근거: 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)

Activity

  1. 26 remaining items

  2. owjs3901 commented on Nov 15, 2026

    @owjs3901
    ContributorAuthor

    main(1160bf646)에 병합된 수정을 확인해 체크리스트를 갱신했습니다.

    새로 체크한 항목 (16건 + 결정 항목 4건)

    아직 열린 PR로만 다루는 항목 (17건): FN-10, JSX-11, DOC-05, DOC-07, DOC-24, DOC-27 (#909), DOC-12 (#909, #911), DOC-15, DOC-16, DOC-20, DOC-21, DOC-22, DOC-23 (#911), DOC-08, DOC-28 (#932), DOC-25, DOC-26 (#954)

    체크하지 않은 결정 항목: "스타일 덮어쓰기 규칙"(limitations 페이지는 있으나, 마이그레이션 문서 안내는 일부 페이지에만 있음), 런타임 전용 API 처리 방식

  3. owjs3901 commented on Nov 17, 2026

    @owjs3901
    ContributorAuthor

    Re-checked against main e9e5801cc.

    Items covered by merged PRs (verified in main): FN-10, JSX-11, DOC-05, DOC-07, DOC-24, DOC-27 (#909); DOC-12, DOC-15, DOC-16, DOC-20, DOC-21, DOC-23 (#911); DOC-08, DOC-28 (#932); DOC-25, DOC-26 (#954). DOC-22 was missed in the Bun README; #993 fixes it. The "runtime-only APIs (D10)" decision item is covered by the "Runtime-only APIs" table in docs/limitations.

    New gaps found and fixed in open PRs:

    Left to open PRs: the StyleX page and sections (#915, #969, #981), the license banner (#987), Bun CommonJS (#984), the Next README sessions (#966), the benchmarks (#985), and the Emotion Global sections (#922).

    Finding outside docs (needs a code fix, not filed yet): in an @emotion/react file, const rules = on ? { color: 'red' } : { color: 'blue' }; <div css={rules} /> compiles silently to className={rules} (an object as className, no CSS). Separately, an extends path that does not exist is silently ignored; #993 documents this, but a warning may be worth adding.

    This issue stays open until #993, #994 and #995 merge.


    main e9e5801cc 기준으로 다시 확인했습니다.

    병합된 PR로 해결된 항목 (main에서 확인): FN-10, JSX-11, DOC-05, DOC-07, DOC-24, DOC-27 (#909); DOC-12, DOC-15, DOC-16, DOC-20, DOC-21, DOC-23 (#911); DOC-08, DOC-28 (#932); DOC-25, DOC-26 (#954). DOC-22는 Bun README에서 빠져 있었고 #993에서 고칩니다. 결정 항목 "런타임 전용 API(D10)"는 docs/limitations의 "Runtime-only APIs" 표로 해결되어 있습니다.

    새로 찾아 열린 PR로 고친 문제:

    열린 PR에 맡긴 부분: StyleX 페이지와 절(#915, #969, #981), 라이선스 배너(#987), Bun CommonJS(#984), Next README 세션(#966), 벤치마크(#985), Emotion Global 절(#922).

    문서 밖에서 발견한 문제 (코드 수정 필요, 아직 이슈로 등록하지 않음): @emotion/react 파일에서 const rules = on ? { color: 'red' } : { color: 'blue' }; <div css={rules} />가 CSS 없이 className={rules}(객체를 className으로)로 조용히 컴파일됩니다. 또 없는 extends 경로는 조용히 무시됩니다. #993에서 문서화했지만, 경고를 추가할 만합니다.

    #993, #994, #995가 병합될 때까지 이 이슈는 열어 둡니다.

  4. owjs3901 commented on Nov 18, 2026

    @owjs3901
    ContributorAuthor

    Re-checked against main a8ad4c58b. #993, #994, #995, #997 and #998 are merged. I ticked every item that main resolves and cited the PR next to each one in the body:

    None of these needed a new PR. The two code gaps the earlier re-check found are fixed:

    Still open: "(recommended) handling of runtime-only APIs (D10)". This item needs an owner decision. docs/limitations already has a "Runtime-only APIs" table describing the current behavior: some APIs are inert, some are build errors, some stay on the source library. The open question is whether that behavior is the policy. I'm leaving this issue open until that is decided.


    main a8ad4c58b 기준으로 다시 확인했습니다. #993, #994, #995, #997, #998이 모두 병합됐습니다. main에서 해결된 항목은 모두 체크했고, 본문의 각 항목 옆에 해당 PR을 적었습니다.

    새 PR이 필요한 항목은 없었습니다. 이전 재확인에서 찾은 코드 문제 두 가지도 해결됐습니다.

    남은 항목: "(권장) 런타임 전용 API(D10) 처리 방식". 이 항목은 오너 결정이 필요합니다. docs/limitations의 "Runtime-only APIs" 표가 이미 현재 동작을 설명합니다. 일부 API는 받아들이되 아무 동작을 하지 않고, 일부는 빌드 에러이며, 일부는 원래 라이브러리에 남습니다. 결정할 것은 이 동작을 정책으로 확정할지입니다. 결정될 때까지 이 이슈는 열어 둡니다.

  5. owjs3901 commented on Nov 18, 2026

    @owjs3901
    ContributorAuthor

    D10 is decided: the owner keeps the current behavior as the policy. The "Runtime-only APIs" table in docs/limitations is the reference. SSR helpers (ServerStyleSheet, StyleSheetManager, CacheProvider) are accepted and do nothing; runtime-only APIs (stylis plugins, create-instance, ThemeContext, withEmotionCache, namespace imports, recipes/sprinkles, …) are build errors naming the location; @emotion/css cache/flush/hydrate/sheet stay with the original library. Every item in this area is now checked, so this audit area is complete.


    D10 결정: 오너가 현재 동작을 정책으로 확정했습니다. docs/limitations의 "Runtime-only APIs" 표가 기준입니다. SSR 도구(ServerStyleSheet, StyleSheetManager, CacheProvider)는 받아들이되 아무 일도 하지 않고, 런타임 전용 API(stylis 플러그인, create-instance, ThemeContext, withEmotionCache, namespace import, recipes/sprinkles 등)는 위치를 알려 주는 빌드 에러이며, @emotion/css의 cache/flush/hydrate/sheet는 원래 라이브러리에 남습니다. 이 영역의 모든 항목이 체크되어 감사를 마칩니다.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions