[RFC] props vs variables boundary

[miroslavstastny]

I still don't have a firm understanding of what defines a boundary between props and variables. I am not proposing any change, I am just playing devil's advocate to make sure stardust architecture is correct. I am trying to define the boundary in order to be able to make decisions when designing component API.

A possible definition which makes sense to me is whatever is used in the component code belongs to props and whatever is used only for styling (=theming) should be part of variables because variables are part of the theme.

Button component example

Why is circular a prop? It does not affect component structure, it is used in theme only to make the button round.

For my custom theme, I need hexagonal button. Why am I not able to achieve that using the same semantics (<Button hexagonal ... />)? And what about the circular prop? Do I need to support it even if my theme does not provide circular button?

[levithomason]

I agree with the presence of this issue. I'm also not 100% sure about the boundary between theme variables and component props. I do have an intuition and proposal for starters.

First, it is important to note that:

1. Stardust props APIs are:
   1. Attempting to describe preexisting UI concepts that have emerged over time.
   2. Proposing a standardized language for these concepts.
   3. Proposing that all component libraries and themes support these concepts.
2. Theme variables are:
   1. Currently loosely defined
   2. Expected to be extensible to suit your company and/or teams' needs

This means that when we publish a component API we are stating that it is a solid UI concept and something that most of the UI community has already shown adoption for. The props API is codifying canonical UI. We're doing this from a descriptivist point of view, not prescribing ideas.

This would make a possible definition something like, whatever is common in the UI community worldwide belongs to props and whatever is rare or unique belongs to variables.

This makes the decision of props vs variable a bit involved since we'll need to do our research and make informed decisions. I propose we do that slow research based work in the /specifications repo and we keep moving forward as quickly and best as we can here in the /react repo.

As our specifications become more solidified, we can iterate the react repo to conform. Just as other frameworks and teams would do.

---

In the case of hexagonal, we can relatively safely say that this is not a common practice in UI and therefore will not be supported as a first class prop today. Other props and ideas might be harder to decide on but research and conversation can sort through those.

[levithomason]

Closing for housekeeping. The current proposal above is our guideline for now. We would like to refine this moving forward. Better ideas welcome please.