Skip to content

docs(landing): state StyleX resolution policy and legacy include() - #969

Open
owjs3901 wants to merge 3 commits into
mainfrom
docs/stylex-resolution-include
Open

owjs3901 wants to merge 3 commits into
mainfrom
docs/stylex-resolution-include

Conversation

@owjs3901

@owjs3901 owjs3901 commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Docs cleanup for deep audit SX-13 / SX-14. Only the StyleX migration page (apps/landing/src/app/(detail)/docs/migration/stylex/page.mdx) is changed. This page has no Korean version.

  • SX-13 (styleResolution): added a "Style resolution" section. It states that Devup UI has no StyleX styleResolution option and follows only StyleX's default policy (property-specificity), and what that means.
    • Within one props()/attrs() call, for the same property and condition, the later style wins.
    • Shorthands are not expanded into longhands, and a later shorthand does not clear earlier longhands. Both classes are applied, and which one takes effect is decided by the order of the generated stylesheet, not the argument order.
    • There is no behavior matching application-order or legacy-expand-shorthands, so it advises switching to longhands.
  • SX-14 (include()): fixed the wording in "Value helpers" that presented include() as a StyleX API. It now says it is a legacy API that Devup UI keeps compiling as an extension.
    • Basis: the stylex.d.ts of @stylexjs/stylex 0.11.1 and 0.19.1 in the lockfile has no include export. It remains only in Devup's @devup-ui/react/compat/stylex declarations.
    • Extractor behavior (extract_style_from_stylex.rs, visit.rs): ...stylex.include(ns.member) inside create() accepts only a namespace defined earlier in the same file, and prepends its classes to its own. Any other argument is a build error.
    • In the "Unsupported APIs" list, include is also marked separately as legacy.

Behavior confirmed while writing the docs (no code changes)

Confirmed by running the latest WASM build directly.

  • With stylex.props(s.btw, s.bw) (borderTopWidth vs borderWidth) or alignItems vs placeItems, the shorthand wins. This is because the stylesheet is sorted alphabetically by property name, and it differs from StyleX's default policy. With margin vs marginTop, the longhand wins. The docs only say this case is not guaranteed.
  • In { ...stylex.include(s0.a), color: 'blue' }, red won by CSS order. Fixed by fix(extractor): let later StyleX keys override an include() #975 (merged): keys written after include() now override the included ones at build time. After merging main, the docs state the new rule instead of the "not guaranteed" caveat.

Overlapping PRs

Test plan

  • bunx prettier --single-quote --no-semi --end-of-line auto --check passes (page.mdx)
  • Checked with git diff --stat that line endings did not rewrite the whole file (14 lines added, 2 removed)
  • Confirmed the documented behavior with codeExtract and getCss of the latest WASM build

요약

딥 오딧 SX-13 / SX-14 문서 정리입니다. StyleX 마이그레이션 페이지(apps/landing/src/app/(detail)/docs/migration/stylex/page.mdx)만 수정했습니다. 이 페이지의 한국어판은 없습니다.

  • SX-13 (styleResolution): "Style resolution" 섹션을 추가했습니다. Devup UI에는 StyleX의 styleResolution 옵션이 없고, StyleX 기본 정책(property-specificity)만 따른다는 점과 그 의미를 적었습니다.
    • 한 props()/attrs() 호출 안에서 같은 속성과 조건이면 나중 스타일이 이깁니다.
    • shorthand를 longhand로 펼치지 않고, 나중 shorthand가 앞선 longhand를 지우지도 않습니다. 두 클래스가 다 붙고, 어느 쪽이 적용될지는 인자 순서가 아니라 생성된 스타일시트 순서로 정해집니다.
    • application-order와 legacy-expand-shorthands에 해당하는 동작은 없으니 longhand로 바꾸라고 안내했습니다.
  • SX-14 (include()): "Value helpers"에서 include()를 StyleX API처럼 소개하던 문구를 고쳤습니다. 지금은 레거시 API이고, Devup UI는 확장으로 계속 컴파일한다고 적었습니다.
    • 근거: lockfile에 있는 @stylexjs/stylex 0.11.1과 0.19.1의 stylex.d.ts에 include export가 없습니다. Devup의 @devup-ui/react/compat/stylex 선언에만 남아 있습니다.
    • 추출기 동작(extract_style_from_stylex.rs, visit.rs): create() 안의 ...stylex.include(ns.member)는 같은 파일에서 앞서 정의된 namespace만 받고, 그 클래스를 자기 클래스 앞에 붙입니다. 그 밖의 인자는 빌드 에러입니다.
    • "Unsupported APIs" 목록에서도 include를 레거시로 따로 표시했습니다.

문서를 쓰다가 확인한 동작 (코드 변경 없음)

최신 WASM 빌드로 직접 돌려서 확인했습니다.

  • stylex.props(s.btw, s.bw)(borderTopWidth 대 borderWidth)나 alignItems 대 placeItems에서는 shorthand가 이깁니다. 스타일시트가 속성 이름의 알파벳 순서로 정렬되기 때문이고, StyleX 기본 정책과 다릅니다. margin 대 marginTop에서는 longhand가 이깁니다. 문서에는 이 경우를 보장하지 않는다고만 적었습니다.
  • { ...stylex.include(s0.a), color: 'blue' }에서 CSS 순서 때문에 red가 이기던 문제는 fix(extractor): let later StyleX keys override an include() #975(병합됨)에서 고쳐졌습니다. 이제 include() 뒤에 쓴 키가 빌드 시점에 덮어씁니다. main을 병합하면서 문서도 "보장하지 않음" 대신 새 규칙을 적도록 바꿨습니다.

겹치는 PR

테스트 계획

  • bunx prettier --single-quote --no-semi --end-of-line auto --check 통과 (page.mdx)
  • git diff --stat으로 줄바꿈 때문에 파일 전체가 바뀌지 않았는지 확인 (14줄 추가, 2줄 삭제)
  • 문서에 쓴 동작을 최신 WASM 빌드의 codeExtract와 getCss로 확인

Refs #690

🤖 Generated with Claude Code

The StyleX migration page now says that Devup UI has no StyleX
styleResolution option and follows only the default policy, and what
that means for shorthands and longhands. It also marks include() as a
legacy API that current @stylexjs/stylex no longer exports, which Devup
UI keeps compiling as an extension, with its same-file restriction and
override caveat.

Refs #690

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@codecov

codecov Bot commented Nov 15, 2026

Copy link
Copy Markdown

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.

owjs3901 and others added 2 commits November 17, 2026 15:00
#975 now lets keys written after include() override the included ones; keep this PR's legacy-include framing and state the new override rule instead of the old 'only added' caveat.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Picks up #990, which fixes main's hook-order and WASM ABI count tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant