docs: document supported syntax, override rules and limitations

[owjs3901]

Refs #693 (K 필수: DOC-01, DOC-10과 열린 PR들의 문서화 항목). main에서 분기했습니다. 문서는 #701–#731이 모두 병합된 뒤의 동작을 기준으로 썼습니다.

요약

README와 문서의 "모든 CSS-in-JS 문법 완벽 지원" 같은 절대적 표현을 걷어내고, 실제로 무엇이 컴파일되고 무엇이 한계인지 정리한 Supported Syntax & Limitations 페이지(/docs/limitations)를 추가합니다.

새 페이지 내용

• 빌드 타임 지원 표: style props, 반응형 배열과 선택자, 조건식, 상수, css()/globalCss()/keyframes(), styled()(attrs, as, withComponent), 테마 읽기, Emotion css prop, <ClassNames>, 컴포넌트 선택자, vanilla-extract, StyleX, Tailwind v4.
• 스타일 덮어쓰기 규칙
  • 빌드가 아는 합성(css(a, b), cx, styled(Base), attrs, style([a, b]), props(a, b), JSX spread, css prop)은 뒤에 오는 쪽이 이깁니다.
  • 반응형 값은 항상 비반응형 값 뒤에 나와 cascade 문제를 막습니다.
  • CSS 특성으로 결정되는 경우: props로 받은 className, 외부 class, 런타임 클래스 문자열, 빌드가 읽지 못하는 styled() base, withComponent(make()), 알 수 없는 spread, key 단위로 못 읽는 StyleX 인자. prop, variant, styled() 확장으로 바꾸라고 안내합니다.
• 브라우저 지원: Baseline 2024 (light-dark(), @layer, :is()).
• css prop: 직접 만든 컴포넌트가 css prop을 받으면 className과 style을 모두 전달해야 한다는 점(D8).
• 런타임 전용 API 처리(D10): ServerStyleSheet/StyleSheetManager/CacheProvider(value 무시)는 동작 없음, stylis plugins 미적용, @emotion/css 런타임 API는 그대로 남음, ThemeProvider의 display: contents, 테스트 유틸과 React Native 미지원, vanilla-extract recipes/sprinkles는 빌드 오류.
• 알려진 한계: 다른 모듈에서 정의한 클래스와 컴포넌트, css()의 런타임 값, 테마 읽기 형태, <ClassNames>의 cx(getClass()), jsxImportSource는 작업 디렉터리의 tsconfig만 읽음(끄는 방법 포함), 빌드가 실행하지 않는 코드.
• 빌드 오류 예시: 모든 오류에 위치, 코드, 필요한 형태가 들어갑니다.

다른 문서 변경

• README(영/한), packages/react/README.md, docs overview, features: 절대적 표현을 바꾸고 새 페이지를 링크했습니다(DOC-01).
• features 페이지의 <Box {...cardStyles} />(css()가 주는 문자열을 spread)를 className={cardStyles}로 고쳤습니다(FN-03).
• styled-components & Emotion 마이그레이션 페이지: "ClassNames, CacheProvider는 대응 없음"이던 표를 현재 동작에 맞게 고치고(css prop, ClassNames, 컴포넌트 선택자, CacheProvider), 한계 절을 추가했습니다(DOC-10).
• 문서 메뉴와 e2e/exported-routes.ts에 새 경로를 추가했습니다.

새로 생기는 오류

• 없습니다(문서 변경).

검증

• bun lint: 기존 경고 2개 외 없음
• landing 빌드 통과, docs/limitations.html 생성 확인
• pre-commit(lint, tarpaulin, bun test) 통과

2026-10-08 업데이트: main 11790bef를 merge commit으로 병합했습니다; 충돌 파일: 없음; 충돌 없이 자동 병합했고, 이미 포함된 squash 원본은 조상 확인 후 ours 전략으로 중복 적용하지 않았습니다.

[github-actions]

Changepacks

@devup-ui/wasm@1.0.83 → 1.0.84 - bindings/devup-ui-wasm/package.json

Patch

• style-order-range only checks styleOrder where the build reads it: a prop of a Devup UI component and a top-level key of a style object passed to css/globalCss/keyframes. A styleOrder key in nested data, in a prop value such as an element passed as a prop, or in a call of a function sharing a name with an Object.prototype member is no longer reported. The array, typography and media rules already skip non-style data, and css-utils-literal-only accepts a css()/keyframes() result held in a const inside a function. No new build errors.
• Tailwind classes in a className: each class compiles on its own and every class Tailwind does not define (custom, plugin and analytics classes) stays as written, where any recognized class used to rebuild the whole className without them and could rewrite part of another class; a class touching a template interpolation (icon-${name}) is left as written, and template classNames no longer get spaces inserted around interpolations. A class whose variant is not understood stays as written instead of applying unconditionally; variants follow Tailwind v4: stacked variants compose (hover:focus: matches the element itself), hover is guarded by @media (hover: hover), group-/peer- use the group/peer marker classes (and group-hover/name), and data-, aria-, has-, nth-, , **, supports-[…] and [&…]/[@media …] variants compile. Utilities emit all their declarations (size-, rounded-t-, truncate, sr-only, not-sr-only, text-sm with its line height, text-sm/6, leading-), translate/rotate/scale/skew compose through Tailwind's individual properties and registered variables (@Property) with negative values kept negative, and arbitrary values follow Tailwind's grammar: spaces for underscores except in url() and var() names, _ for an underscore, spaces around math operators, type hints, [property:value] and (--variable) shorthands. Words that only share a utility's prefix (select-wrapper, order-summary, cursor-foo) are no longer compiled

@devup-ui/bun-plugin@1.0.22 → 1.0.23 - packages/bun-plugin/package.json

Patch

• Bun plugin works with Bun.build: DevupUI() (from @devup-ui/bun-plugin/register) serves the generated stylesheet to the bundler's CSS loader once every other module is loaded, so the build emits a CSS output with the styles of the whole bundle instead of an empty module; class names are short there and readable under the runtime (debug option). Files importing the packages Devup UI takes the place of (@emotion/react, @emotion/styled, styled-components, @vanilla-extract/css), @stylexjs/stylex, or a subpath or re-export of these or @devup-ui/react, are compiled instead of skipped

@devup-ui/components@0.1.60 → 0.1.61 - packages/components/package.json

Patch

• Auto-update: depends on '@devup-ui/react' via a local workspace dependency

@devup-ui/eslint-plugin@1.0.22 → 1.0.23 - packages/eslint-plugin/package.json

Patch

• style-order-range only checks styleOrder where the build reads it: a prop of a Devup UI component and a top-level key of a style object passed to css/globalCss/keyframes. A styleOrder key in nested data, in a prop value such as an element passed as a prop, or in a call of a function sharing a name with an Object.prototype member is no longer reported. The array, typography and media rules already skip non-style data, and css-utils-literal-only accepts a css()/keyframes() result held in a const inside a function. No new build errors.

@devup-ui/next-plugin@1.0.90 → 1.0.91 - packages/next-plugin/package.json

Patch

• Auto-update: depends on '@devup-ui/plugin-utils' via a local workspace dependency

@devup-ui/plugin-utils@1.0.17 → 1.0.18 - packages/plugin-utils/package.json

Patch

• Webpack and Rsbuild builds hold every style in their stylesheets: a stylesheet module is built on its first import, so styles extracted later (the global styles of files webpack or Rsbuild reached late, often outside src) were missing from the output. The files the entries reach under src are now extracted before the build, the shared base on disk is kept current, and when a stylesheet still changed during the build it is compiled once more, writing only the complete result. Rsbuild serves each stylesheet from the current sheet instead of a module-wide string kept only when it grew, which left edits that shortened the CSS and later builds in the same process stale. plugin-utils adds computeReachableFiles

@devup-ui/react@1.0.44 → 1.0.45 - packages/react/package.json

Patch

• The README no longer claims every CSS-in-JS pattern compiles: it describes what the build compiles and that anything it cannot know is a CSS variable or a located build error, and links the new Supported Syntax & Limitations page, which lists what compiles, the style override rules (where a later part wins and where the CSS cascade decides), Baseline 2024 browser support, that a component taking the css prop must pass className and style on, the runtime-only APIs and how each is handled, and the known limitations

@devup-ui/reset-css@1.0.31 → 1.0.32 - packages/reset-css/package.json

Patch

• Auto-update: depends on '@devup-ui/react' via a local workspace dependency

@devup-ui/rsbuild-plugin@1.0.67 → 1.0.68 - packages/rsbuild-plugin/package.json

Patch

• Webpack and Rsbuild builds hold every style in their stylesheets: a stylesheet module is built on its first import, so styles extracted later (the global styles of files webpack or Rsbuild reached late, often outside src) were missing from the output. The files the entries reach under src are now extracted before the build, the shared base on disk is kept current, and when a stylesheet still changed during the build it is compiled once more, writing only the complete result. Rsbuild serves each stylesheet from the current sheet instead of a module-wide string kept only when it grew, which left edits that shortened the CSS and later builds in the same process stale. plugin-utils adds computeReachableFiles

@devup-ui/vite-plugin@1.0.73 → 1.0.74 - packages/vite-plugin/package.json

Patch

• Auto-update: depends on '@devup-ui/plugin-utils' via a local workspace dependency

@devup-ui/webpack-plugin@1.0.71 → 1.0.72 - packages/webpack-plugin/package.json

Patch

• Webpack and Rsbuild builds hold every style in their stylesheets: a stylesheet module is built on its first import, so styles extracted later (the global styles of files webpack or Rsbuild reached late, often outside src) were missing from the output. The files the entries reach under src are now extracted before the build, the shared base on disk is kept current, and when a stylesheet still changed during the build it is compiled once more, writing only the complete result. Rsbuild serves each stylesheet from the current sheet instead of a module-wide string kept only when it grew, which left edits that shortened the CSS and later builds in the same process stale. plugin-utils adds computeReachableFiles

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.