```
**✅ Conditional props pattern**
Use `stylex.props()` with boolean expressions to conditionally apply generated classes:
```tsx
const styles = stylex.create({
base: { color: 'gray' },
active: { color: 'blue' },
});
export const Component = ({ isActive }: { isActive: boolean }) => (
Composable styles
);
```
For ancestor and descendant states, skipping `stylex.when` leads to fragile selectors or JavaScript state syncing. Use the dedicated helpers instead:
```tsx
const styles = stylex.create({
control: {
...stylex.when.ancestor(':hover', { opacity: 0.8 }),
...stylex.when.descendant(':focus', { borderColor: 'blue' }),
...stylex.when.siblingBefore(':checked', { background: 'green' }),
},
});
```
## Component Scope and Integration
Using generic `
` elements instead of the `Link` component prevents proper routing integration with Next.js or React Router. Always render links via `useLinkComponent()` or within a `LinkProvider` to preserve the abstraction layer so the underlying router can be swapped.
For form controls, avoid the default marker which leaks hover and focus states from outer containers (causing popover glitches). Create component-scoped markers using `stylex.defineMarker()`:
```tsx
const marker = stylex.defineMarker();
const styles = stylex.create({
control: { marker: true },
});
```
## Performance and Maintenance
Redundant CSS bloats stylesheets and hurts performance. Rely on StyleX's automatic deduplication and keep selectors lean using the `stylex.props()` composability model. The [`internal/eslint-plugin-astryx/README.md`](https://github.com/facebook/astryx/blob/main/internal/eslint-plugin-astryx/README.md) file contains ESLint rules that automatically catch many of these anti-patterns during development.
Before modifying components, query the documentation using the CLI command shown in [`packages/cli/README.md`](https://github.com/facebook/astryx/blob/main/packages/cli/README.md):
```bash
$ASTRYX component Button --dense
```
## Summary
- **Never hard-code values**—use `stylex.defineVars` and theme tokens for radii, colors, and spacing.
- **Avoid CSS nesting** with `&`—prefer `stylex.when.ancestor()` and `stylex.when.descendant()` for state-based styling.
- **Skip inline styles**—encode dynamic values within `stylex.create()` and apply conditionally via `stylex.props()`.
- **Don't toggle classes manually**—use the declarative `stylex.props(condition && styles.variant)` pattern.
- **Use `stylex.firstThatWorks()`** instead of manual CSS fallbacks.
- **Render links via `useLinkComponent()`** rather than generic `` tags to preserve routing integration.
- **Scope form markers** with `stylex.defineMarker()` to prevent state leakage from containers.
## Frequently Asked Questions
### What happens if I use inline style objects with Astryx?
Inline `style` props bypass StyleX's static analysis, which prevents compile-time optimizations and can lead to duplicated CSS in the final bundle. Always encode dynamic values inside `stylex.create()` functions or use the `stylex.props(condition && styles.x)` pattern to maintain design system guarantees.
### How do I handle hover states without CSS nesting?
Use `stylex.when.ancestor(':hover')` or `stylex.when.descendant(':focus')` to express parent-child relationships. This maintains the flat CSS structure that StyleX compiles while avoiding the specificity issues associated with nested `&` selectors, as documented in [`packages/core/README.md`](https://github.com/facebook/astryx/blob/main/packages/core/README.md).
### Why should I avoid manual class name toggling?
Toggling classes via `className={cond ? 'a' : 'b'}` undermines StyleX's declarative model and risks class name collisions. The `stylex.props()` API safely composes generated class names and only applies them when conditions are true, ensuring consistency with the design system.
### How do I verify I'm not using anti-patterns in my codebase?
The `internal/eslint-plugin-astryx` package provides ESLint rules that catch common anti-patterns automatically. Additionally, use the CLI command `$ASTRYX component --dense` to query component documentation before implementation, as documented in [`packages/cli/README.md`](https://github.com/facebook/astryx/blob/main/packages/cli/README.md).