Repository navigation
Closed
Labels
documentationImprovements or additions to documentationImprovements or additions to documentation
Description
문서가 실제 동작과 다르거나 빠진 부분입니다. 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-234showsconst cardStyles = css(...)followed by<Box {...cardStyles} />; the API page sayscssreturns a string atdocs/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.tsxemits slot 3 atmin-width:992pxand slot 5 at1600px; typography docs list1024pxand1640px(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 markslight-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-themevariables.
- 근거: Shared two-theme colors emit only
- 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 instyled-dynamic.tsx; docs say “A whole style object computed that way (css(makeStyles()),styled.div(makeStyles())) is a build error” atdocs/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.
- 근거: types generate group forms for every simple/advanced selector and support direct
선택 (16)
- DOC-05 (P2, MISMATCH) N/M-base alphabet/count documentation is wrong — docs(landing): correct remaining audit mismatches #909
- 근거: 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 — docs(landing): correct remaining audit mismatches #909
- 근거: 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 — docs(figma-plugin): link the plugin ID the plugin repository publishes #932
- 근거: legacy ID 1412341601954480694 vs current ID 1446848873498976065
- 수정 방향: verify live listing and consolidate
- DOC-12 (P2, PERF) “Latest” benchmarks/version are stale — docs: refresh package READMEs and agent metadata #911
- 근거: 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 — docs: refresh package READMEs and agent metadata #911
- 근거: packages/components README installs/describes @devup-ui/react
- 수정 방향: rewrite package-specific README
- DOC-16 (P2, MISMATCH) reset-css README omits its actual API — docs: refresh package READMEs and agent metadata #911
- 근거: 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 — docs: refresh package READMEs and agent metadata #911
- 근거: 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 — docs: refresh package READMEs and agent metadata #911 (links now point to the root
README_ko.md)- 근거: 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 — docs: refresh package READMEs and agent metadata #911; Bun README in docs: fix the Bun build setup and devup.json plugin examples, document extends #993
- 근거: 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 — docs: refresh package READMEs and agent metadata #911
- 근거: 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 — docs(landing): correct remaining audit mismatches #909
- 근거: 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 — test(docs): check documented examples against the emitted CSS #954
- 근거: 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 — test(docs): check documented examples against the emitted CSS #954
- 근거: 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)
_firstselector maps to nonstandard:firstin docs — docs(landing): correct remaining audit mismatches #909- 근거: 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 — docs(figma-plugin): link the plugin ID the plugin repository publishes #932
- 근거: external plugin absent; two stale/conflicting pages
- 수정 방향: consolidate, date and link authoritative plugin docs
Metadata
Metadata
Assignees
Labels
documentationImprovements or additions to documentationImprovements or additions to documentation
Activity
docs: document supported syntax, override rules and limitations
chore: satisfy clippy assert_is_empty lint on Rust 1.99
docs: update legacy theme schema and declaration paths
docs: clarify vanilla-extract ordinary-module support
docs: refresh extractor guide with actual probe output
docs: lock breakpoint tables and complete verified stylesheet examples
docs: synchronize root README examples with actual output
fix(extractor): compose imported vanilla-extract styles exactly
fix(extractor): preserve vanilla-extract selector identities and exports
fix(extractor): evaluate static vanilla-extract modules across script…
fix(extractor): evaluate exact vanilla-extract slices in mixed modules
fix(extractor): evaluate demand-selected vanilla-extract module views
fix(extractor): preserve inherited properties in demanded values
fix(extractor): resolve imported vanilla-extract values and API prove…
26 remaining items
docs: correct Button and optimization output examples
fix(extractor): preserve styled conditional spread precedence
owjs3901 commentedon Nov 15, 2026
main(
1160bf646)에 병합된 수정을 확인해 체크리스트를 갱신했습니다.새로 체크한 항목 (16건 + 결정 항목 4건)
docs/limitations/page.mdx의 "Browser support" 절(Baseline 2024 명시)packages/eslint-plugin/src/rules/style-order-range/README.md(fix(types): align remaining StyleX, shorthand and lint contracts #763: Devup 컴포넌트 import 예제, 엄격한 문자열 규칙)docs/limitations/page.mdxstyle전달:docs/limitations/page.mdx"Thecssprop on your own components"docs/migration/tailwind/page.mdx(breakpoint, 지원 범위)docs/build-errors)아직 열린 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 처리 방식
docs(figma-plugin): link the plugin ID the plugin repository publishes (
Read vanilla-extract stylesheet exports from ordinary modules (#973)
test(docs): check documented examples against the emitted CSS (#954)
owjs3901 commentedon Nov 17, 2026
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:
import '@devup-ui/bun-plugin'beforeBun.build. That registers a runtime plugin, whichBun.buildnever runs (checked with Bun 1.4.4), so bundles shipped uncompiled components. Both pages now useplugins: [DevupUI()].withDevupUIdefault export.extendswas undocumented; it is now documented.d0/d1(DOC-22).constnow compiles, a parse error is now reported first, and a self-including StyleXinclude()now reports TDZ.@emotion/cssamong the default aliases.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/reactfile,const rules = on ? { color: 'red' } : { color: 'blue' }; <div css={rules} />compiles silently toclassName={rules}(an object as className, no CSS). Separately, anextendspath 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로 고친 문제:
Bun.build전에import '@devup-ui/bun-plugin'을 하라고 안내했습니다. 이 import는 런타임 플러그인을 등록하는데,Bun.build는 이를 실행하지 않습니다 (Bun 1.4.4에서 확인). 그래서 컴파일되지 않은 컴포넌트가 번들에 들어갔습니다. 두 페이지 모두plugins: [DevupUI()]를 쓰도록 바꿨습니다.withDevupUIdefault export를 썼습니다.extends를 문서화했습니다.d0/d1이 남아 있었습니다 (DOC-22).const가 이제 컴파일됨, 파싱 에러가 먼저 보고됨, 자기 자신을 include하는 StyleXinclude()가 TDZ로 보고됨.@emotion/css도 넣었습니다.열린 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가 병합될 때까지 이 이슈는 열어 둡니다.
fix(plugin-utils): warn when devup.json extends a file that does not …
docs: fix the Bun build setup and devup.json plugin examples, documen…
docs(build-errors): match three examples to main and document plugin …
docs(migration): say which style wins and list every default alias (#995
fix(extractor): compile a const choosing styles that the css prop rea…
owjs3901 commentedon Nov 18, 2026
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:docs/migration.features/page.mdx:240now states whencss(makeStyles())/styled.div(makeStyles())compiles,core-concepts/nm-basedocuments the 27 single-character names,devup-jsondocuments<distDir>/theme.d.ts, and the selector page maps_firstto:first-child.README_ko.md.1412341601954480694, is left in the repo.None of these needed a new PR. The two code gaps the earlier re-check found are fixed:
extendsnames a missing file.constchoice of styles that thecssprop reads.Still open: "(recommended) handling of runtime-only APIs (D10)". This item needs an owner decision.
docs/limitationsalready 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을 적었습니다.docs/migration"Which style wins" 섹션README_ko.md를 가리킵니다.1412341601954480694하나만 남았습니다.새 PR이 필요한 항목은 없었습니다. 이전 재확인에서 찾은 코드 문제 두 가지도 해결됐습니다.
extends가 없는 파일을 가리키면 경고합니다.cssprop이 읽는, 스타일 중 하나를 고르는const를 컴파일하거나 에러로 알립니다.남은 항목: "(권장) 런타임 전용 API(D10) 처리 방식". 이 항목은 오너 결정이 필요합니다.
docs/limitations의 "Runtime-only APIs" 표가 이미 현재 동작을 설명합니다. 일부 API는 받아들이되 아무 동작을 하지 않고, 일부는 빌드 에러이며, 일부는 원래 라이브러리에 남습니다. 결정할 것은 이 동작을 정책으로 확정할지입니다. 결정될 때까지 이 이슈는 열어 둡니다.owjs3901 commentedon Nov 18, 2026
D10 is decided: the owner keeps the current behavior as the policy. The "Runtime-only APIs" table in
docs/limitationsis 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/csscache/flush/hydrate/sheetstay 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는 원래 라이브러리에 남습니다. 이 영역의 모든 항목이 체크되어 감사를 마칩니다.