Proposal: CSS Variables in Media Queries

[divineniiquaye]

Summary

I'd like to propose adding support for CSS custom properties (variables) within media queries in Uniwind. This would enable responsive and adaptive styling where variable values can change based on screen dimensions, device orientation, and color scheme preferences.

Issue: #242

Problem

Currently, CSS variables in Uniwind are static - once defined, they cannot adapt to different device conditions. This creates limitations when building responsive applications where you might want:

• Responsive typography: Font sizes that scale with screen width
• Adaptive spacing: Padding/margins that adjust for different screen sizes
• Orientation-aware layouts: Different values for portrait vs landscape
• Theme-aware styling: Variables that respond to light/dark mode preferences

Current Limitation Example

@layer theme {
  :root {
    --text-size: 16px;  /* Static value, can't change */
  }
}

If you want larger text on tablets, you'd need to use JavaScript or create separate classes, which isn't as elegant as native CSS media queries.

Proposed Solution

Allow CSS variables to be defined conditionally within media queries, similar to how standard CSS properties work:

@layer theme {
  :root {
    --text-size: 16px;
  }
}

@media (min-width: 768px) {
  :root {
    --text-size: 24px;  /* Larger text on tablets */
  }
}

.text {
  font-size: var(--text-size);
}

Supported Media Query Types

The implementation would support:

1. Width-based queries

   • min-width - For responsive breakpoints
   • max-width - For maximum width constraints

2. Orientation queries

   • orientation: portrait
   • orientation: landscape

3. Color scheme queries

   • prefers-color-scheme: light
   • prefers-color-scheme: dark

4. Combined conditions

   • Multiple conditions with and operator
   • Example: @media (min-width: 768px) and (orientation: landscape)

Use Cases

1. Responsive Typography

:root {
  --heading-size: 1.5rem;
}

@media (min-width: 768px) {
  :root {
    --heading-size: 2.5rem;
  }
}

2. Orientation-Aware Spacing

:root {
  --container-padding: 1rem;
}

@media (orientation: landscape) {
  :root {
    --container-padding: 2rem;
  }
}

3. Theme-Aware Variables

:root {
  --border-color: #000000;
}

@media (prefers-color-scheme: dark) {
  :root {
    --border-color: #ffffff;
  }
}

4. Complex Responsive Design

:root {
  --sidebar-width: 0px;
}

@media (min-width: 1024px) and (orientation: landscape) {
  :root {
    --sidebar-width: 250px;
  }
}

Implementation Approach

Runtime Resolution

Variables would be resolved at runtime based on current device state:

• Screen dimensions (tracked via UniwindRuntime)
• Device orientation
• Current color scheme/theme

Dependency Tracking

The system would automatically track dependencies and trigger updates when:

• Screen dimensions change
• Device orientation changes
• Color scheme preference changes

Performance Considerations

• Variables are only processed when media queries are present
• Efficient matching algorithm to find the best variant
• Reactive updates only when relevant dependencies change

Questions for Discussion

1. Scope: Should we start with basic width/orientation/color-scheme support, or include additional media query features from the start?

2. Syntax: Does the proposed CSS syntax align with Uniwind's design philosophy? Any concerns about compatibility?

3. Performance: Are there any performance concerns with runtime variable resolution? Should we consider compile-time optimizations?

4. API: Should this work seamlessly with existing useCSSVariable hook, or do we need additional APIs?

Potential Challenges

• Runtime evaluation of media queries (vs compile-time)
• Ensuring reactive updates work correctly with React Native's rendering
• Handling edge cases with multiple matching variants
• Performance with many variables and conditions

Next Steps

If this proposal is accepted, I'm happy to:

• Implement the feature
• Write comprehensive tests
• Update documentation
• Create examples and demos

Feedback Requested

I'd love to hear thoughts from:

• @jpudysz, @Brentlok maintainers - Does this align with the project vision?
• Community members - Would this feature be useful for your use cases?
• Anyone with concerns or suggestions - All feedback is welcome!

---

Note: I've already implemented a working prototype of this feature PR 261, but I wanted to discuss it with the community first before proposing it as an official feature. The implementation includes comprehensive test coverage and performance optimizations.

Let me know what you think! 🚀

[Brentlok]

Hi, first of all thanks for detailed discussion

1. Scope: Should we start with basic width/orientation/color-scheme support, or include additional media query features from the start?

What kind of additional media query features? I think that uniwind supports only the one that you mentioned and I don't think that native side is compatible with something else 🤔

2. Syntax: Does the proposed CSS syntax align with Uniwind's design philosophy? Any concerns about compatibility?

Syntax is fine, generally our idea is to have web compatible css so no parsing needs to be applied for the web. Of course sometimes it's not possible but in this case it just works 👍

3. Performance: Are there any performance concerns with runtime variable resolution? Should we consider compile-time optimizations?

I've seen the initial implementation and this could be improved. I think that resolution of variables should happen only once in

uniwind/packages/uniwind/src/core/native/store.ts

Line 49 in 555f3b7

reinit = (generateStyleSheetCallback?: GenerateStyleSheetsCallback) => {

like it happens for platform/theme variables. Every group of variables under media query should have a listener that would update "global" variables from store

uniwind/packages/uniwind/src/core/native/store.ts

Line 17 in 555f3b7

vars = {} as Record<string, unknown>

and will notify listeners with StyleDependency.Variables. We can also refactor theme variables so they will follow the same logic

4. API: Should this work seamlessly with existing useCSSVariable hook, or do we need additional APIs?

Yes it should work seamlessly

---

We also need to think about order/priority of resolving those in css this happens automatically but not there

I will take a look at this feature, but it doesn't really have high priority because only one person asked for it, and the topic isn't really continued. If you wish you can try to implement it we're always happy for contributions outside our core team. It's pretty big feature and we need to discuss some things before the final implementation, but in the meantime you can start with implementing just width/height media queries variables with the logic I've suggested - no tests, no refactors needed, just a starting point for future implementation.

Looking forward to your thoughts 😄

[divineniiquaye]

Great, thanks. I'll start with an implementation for width/height media queries following your suggested solution

[divineniiquaye]

I've open a pull request on it #274, I was able to find a way to resolve all media queries directly in the metro processor. But I'll need your review on it.

[divineniiquaye]

Updated as PR #335