docs(repo): codify StyleX best practices in the Mosaic skill#9238
Conversation
Expand references/stylex.md into an evidence-backed do/don't guide from a sweep of the astryx design system: sections on breaking up stylex.create (base + variant maps + state objects) and dynamic styles (write-a-var vs set-property, perf model). Fix marker files to .markers.stylex.ts, add scoped ancestor states, and record the Mosaic convention that stylex.create lives in a co-located .styles.ts, never inline in the .tsx.
🦋 Changeset detectedLatest commit: 00df215 The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughAdded a changeset for the Mosaic StyleX best-practices documentation. Expanded the StyleX reference with file-layout rules, token conventions, static-analysis requirements, composition patterns, conditional states, scoped ancestor markers, dynamic-style guidance, prop precedence, and CSS feature caveats. Estimated code review effort: 3 (Moderate) | ~25 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/skills/mosaic/references/stylex.md:
- Around line 252-253: Fix the malformed inline code spans in the style
examples: keep the full tree-row indentation expression and line-clamp
expression, including their internal spaces, within a single code span so the
Markdown passes MD038. Leave the staggered animationDelay example unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro Plus
Run ID: 2eea5fd0-0e18-44ec-86d8-385453c431e5
📒 Files selected for processing (2)
.changeset/mosaic-stylex-best-practices.md.claude/skills/mosaic/references/stylex.md
🔗 Linked repositories identified
CodeRabbit considers these linked repositories for cross-repo context during reviews:
clerk/clerk_go(manual)clerk/dashboard(manual)clerk/accounts(manual)clerk/backoffice(manual)clerk/clerk(manual)clerk/clerk-docs(manual)clerk/cloudflare-workers(manual)clerk/cli(auto-detected)clerk/clerk-ios(auto-detected)clerk/clerk-android(auto-detected)
| tree-row indent `(depth-1) \* step`, a line clamp `n => ({ WebkitLineClamp: n })`, | ||
| a staggered `animationDelay`. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Fix the malformed inline code spans.
The indentation and line-clamp examples contain spaces inside code spans and trigger MD038. Keep the entire expression inside one code span.
Proposed fix
- tree-row indent `(depth-1) \* step`, a line clamp `n => ({ WebkitLineClamp: n })`,
+ tree-row indent `(depth - 1) * step`, a line clamp `n => ({ WebkitLineClamp: n })`,🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 252-252: Spaces inside code span elements
(MD038, no-space-in-code)
[warning] 252-252: Spaces inside code span elements
(MD038, no-space-in-code)
[warning] 253-253: Spaces inside code span elements
(MD038, no-space-in-code)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/skills/mosaic/references/stylex.md around lines 252 - 253, Fix the
malformed inline code spans in the style examples: keep the full tree-row
indentation expression and line-clamp expression, including their internal
spaces, within a single code span so the Markdown passes MD038. Leave the
staggered animationDelay example unchanged.
Source: Linters/SAST tools
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/electron
@clerk/electron-passkeys
@clerk/eslint-plugin
@clerk/expo
@clerk/expo-google-signin
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/hono
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/react
@clerk/react-router
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/ui
@clerk/upgrade
@clerk/vue
commit: |
2 participants
Summary
Expands
.claude/skills/mosaic/references/stylex.mdinto an evidence-backed do/don't StyleX authoring guide, from a full sweep of the astryx design system (~120 components).New/rewritten sections:
stylex.create— base object + prop-keyed variant maps + small state objects, composed in onestylex.props(...); don't monolith, don't per-property, don't inline-ternary a variant (that's a missing map).--varand let a static rule consume it (one atom, survives consumer@mediaoverrides, inherits to descendants) vs. set the property raw (per-instance only).stylex.when.ancestor()+defineMarker()in place of parent-selector hacks.Corrections / decisions
<comp>.markers.stylex.ts(a.stylex.tsdefine-primitive file), not.markers.ts— verified against the@stylexjs/eslint-pluginenforce-extensionrule source..stylex.ts=define*only;createmay not live there) from Mosaic house convention:stylex.createlives in a co-located<comp>.styles.ts, never inline in the.tsx. This is a deliberate divergence from astryx (which inlines), recorded as our choice rather than a research finding.Verification
Key claims spot-checked against astryx source:
when.ancestor/defineMarker(real), dynamic functions (47 uses),firstThatWorks/attrs(0 uses), the CodeBlock/AvatarGroup var-writing pattern, and theenforce-extensionbehavior.Changeset
Empty — repo/tooling-only doc change, no user-facing package impact.