facebook / facebook/astryx

[RFC] Support TailwindCSS integration with Astryx

Open
#4,127 1 comment 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
TypeScript
Stars
13k
Forks
1.1k
Avg merge
1d 15h
Merged PRs (30d)
690

Description

### Problem Statement

Astryx currently uses stylex for styling and does not provide official documentation, adapters, or examples for integrating TailwindCSS. Many projects and contributors prefer Tailwind's utility-first approach; lacking clear support increases friction for adoption and migration.

### Evidence of Demand

Tailwind is widely used across the React ecosystem and many component libraries provide integration guides or adapter tooling. There are requests across the community for utility-first styling and examples where integrating Tailwind with other design systems has simplified styling and lowered onboarding friction.

### Why Existing Components Don't Cover This

I attempted to compose Astryx components with Tailwind classes by wrapping components and applying className, but encountered conflicts with stylex-generated class names and theme tokens. Some components rely on internal stylex tokens that are not directly exposed as Tailwind utilities, resulting in inconsistent spacing and colors.

### Rough Approaches Considered

Option A: Add official documentation and examples showing best practices for using Tailwind alongside Astryx (preferred for minimal invasiveness).

Option B: Provide a small adapter utility that maps Astryx theme tokens to Tailwind config (colors, spacing) and documents how to extend tailwind.config.js.

Option C: Offer an optional build-time plugin that generates Tailwind-compatible utility classes from Astryx tokens for teams that want a tighter integration.

Include consumer code examples for each approach.

### Accessibility Considerations

This change does not alter DOM semantics. Ensure guidance includes accessibility notes for using utility classes with ARIA attributes and keyboard interactions where relevant.

### Performance Considerations

_No response_

### Pre-submission Checklist

- [x] I have read the [Contributing guide](https://github.com/facebook/astryx/wiki/Contributing)
- [x] I have read the [API Conventions](https://github.com/facebook/astryx/wiki/API-Conventions)
- [x] I have checked that existing Astryx components cannot compose to solve this
- [x] This is a general-purpose UI pattern (not specific to one product)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.