Documentation not clear for beginners

[LeonardoGentile]

Hello there,
I'm a beginner at theme-ui and after reading the docs multiple times I still have many unanswered questions, I hope someone could shed some light here.

Theme UI is a library for creating themeable user interfaces based on constraint-based design principles.

Now, I've assumed some of those constraint were made by default by theme-ui, and this belief was supported by the line were the docs mentioned the support for Typography.js.

What I mean, from my understanding, these constraints are only set by the developer by customizing all the possible (but limited) choices of the theme fields.
But even limiting the choices for fonts, fontSizes, fontWeights, lineHeights, letterSpacings, ectr you still have to make many decisions of how to mix'n'match all these possible values without messing up.

What I mean, for example, not being a designer myself, I don't know which line fontSizes +fontWeights + lineHeights + letterSpacings would play nice for that particular value of fonts for a heading H2.

I've assumed someone else made these choices for me and packed them up into a...theme, but that's not the case.

The same applies for breakpoint and media queries, the lack of defaults just puzzles me, how is that possible that I have to define all of these commonly used defaults?

---

Another misunderstood concept: none of the value defined into the theme are automatically mapped to html elements by default so I guess I would have to add those value myself.

That mean that if I want to assign all the p a certain font size for my site I should either create a react component:

const function Paragraph({children}) {
  return () {
    <p sx={{fontsize: 0}}>{children}</p>
  }
}

And then use the Paragraph component instead of 'p' when I need it?
Or should I define a p properties into the styles property and use <Themed.p>.

All of this is just confusing 😕

[braaar]

I am probably quite late to the party, but here goes.

The same applies for breakpoint and media queries, the lack of defaults just puzzles me, how is that possible that I have to define all of these commonly used defaults?

You can copy an existing theme and start using it if that's what you'd like. Theme UI is a framework for theming, not a theme.

I don't think it's such a huge issue to find the right padding/margin/size for your purposes. And to make it responsive to screen sizes you can use breakpoints like so:

<Box sx={{ m: [2, 3, 4], borderRadius: [3, 3, 2], borderColor: 'secondary' }}>
  <Text sx= {{ fontSize: [4, 3, 3] }}>Hello there!</Text>
</Box>

Tweak the values so they look nice for your component, and there you are. If you use the same values in many places you can define variants (which would function quite like a html class) so you can do this:

<Text variant={"helloText"}>Hello there!</Text>

And then use the Paragraph component instead of 'p' when I need it?

You shouldn't use <p> in a Theme UI project. Replace all your <p> tags with <Paragraph> from Theme UI

Likewise you shouldn't use <div>., either. Use Box, Flex, Grid, Card, etc.

I would start with the theme from the docs to get the arrays with the sizes and stuff, and add more as needed (such as radii)

Here's a theme with a demo page you can look at to see a real world example.