Initial definition

[jxnblk]

This issue is meant to be the canonical place for discussion about the initial scope and details of the theme specification.

[zethussuen]

Hi Brent!

As a designer, I'm a huge fan of styled-system and all of the work you've done in this space. As an engineer, I constantly advocate for styled-system + typescript. Personally, I want to see some sort of type recommendation in theme-specification. I would love to be able to swap theme specs in and out and not worry whether widths have been defined as a number (10) vs string (10px, 10em, etc). I can also see how this may be restrictive. Would love to hear your thoughts on the topic.

[souporserious]

Super excited to see this getting started!

I've been thinking about this spec the last couple of days and wondering if you have any thoughts on how multiple sets of fontSizes could be handled? Similar to how Github uses two sets of font sizes across viewports. Do you think it would be best handled in each respective application? I'm thinking it would be nice to have that relationship accessible in the spec for things like documentation, tooling, etc.

[jxnblk]

@souporserious I'm hoping that the idea of scales being objects means that you would have one master fontSizes array or object, then use that as the basis for subsets like what you're describing. It could be additional custom fields like theme.mobileFontSizes and theme.desktopFontSizes or a nested object within the root scale, like theme.fontSizes.mobile. Just like colors, I think trying to make a one-size-fits all abstraction at the scale definition level will be very difficult, and this is more meant to start more from a where do I find values for font sizes perspective, if that makes sense

[jxnblk]

@zethussuen thanks! I think this initial spec is meant to be fairly loosely defined when it comes to what you put in the scales. That said, an extension of this spec could absolutely layer a type system on top – I think the PR here sort of leans that direction: styled-system/styled-system#432

[souporserious]

Totally! That makes sense. I like settling on a key-value structure that everyone can adhere to, which right now seems great to me 👍.

[jxnblk]

Just opened a PR for discussion about width and height properties here: #2

[Grsmto]

Related to @zethussuen comment, we are using TypeScript with styled-system and the way you define aliases for a scale does not work in a strictly typed context because you are applying a value to an array, which is considered an error in TS.
I don't know if you want to consider TS for the spec but that's how we had to do to avoid the typing error:

const fontSizes = {
  0: '0.75rem', // 12px
  1: '0.875rem', // 14px
  2: '1rem', // 16px
  3: '1.125rem', // 18px
  4: '1.25rem', // 20px
  5: '1.5rem', // 24px
  6: '1.75rem', // 28px
  7: '2rem', // 32px
  8: '2.25rem', // 36px
  9: '2.625rem', // 42px
};

fontSizes.baseText = fontSizes[1];

This way the fontSizes is an object and not an array but still can be accessed just like an array.

[jxnblk]

@Grsmto Yeah, this spec should "work" for any language really. If you have to slightly alter what an object looks like for TS, I think that's totally valid. The aliasing example uses JS as a lingua franca to describe one possible approach to scale definition

[nniesen]

It's awkward that space is the only one that is collection and is not plural.

[timhudson]

I'm so glad to see this discussion and repo! After reading through the spec and everyones feedback, I wrote down my thoughts. This will be a bit of a dump, apologies in advance.

1. Static definitions JSON/YML

This has been discussed in styled-system/styled-system#432 (comment) and touched on above.

To increase the specs reach and potential adoption, it's certainly worth considering embracing a baseline of everything being statically defined. While any language could be used to generate a spec-compliant static theme, it's this common output that could be consumed predictably by tooling of any language or platform. I agree with the earlier sentiment that JSON would be a good choice.

However, we'd have to create or adopt a standard for referencing values. Style Dictionary solves this with a template-tag-esque approach.

2. Functions as values

This flies in the face of static definitions, but some scales could better be described through a function, especially when unbounded. A decent example is the space scale. This could reasonably be described as n => n * 1.5. Color scales could use a more complex function that understands color. Several systems use functions and omitting them here may limit this specs reach.

I'm on the fence as I would favor static definitions. Could they reasonably co-exist? It's a little convoluted but I could see this solved using function names which map to externally defined implementations.

"space": "fn:space" // gross prefix

export const space = n => n * 1.5

3. Abstracting away platform specific language/concepts

Considering how a design language can be applied across many platforms and technologies, how can we abstract away platform specific language without losing the specs simplicity and familiarity? While I don't think it's practical to have a completely generic spec, that sounds unnecessarily plain, I do wonder if we can take things a little further than where they are currently.

These stand out to me as potentially CSS specific:

• mediaQueries
• maxWidths, minWidths, maxHeights and minHeights?
  • I can't definitively say these are CSS specific but I'm skeptical
• zIndices
• Any mention of CSS outside the context of the Key Reference
• Excluded Values could be reframed to discuss generally what is out of scope for this spec, using CSS as an example.

As for Key Reference mappings, we could make room for adding more key mappings beyond CSS. However, this has me questioning whether mappings should even be part of the spec. I'm tempted to consider that a tooling concern. I'm not sure.

4. Prior art

What makes this unique or more capable than existing solutions? Answering this can help folks see the value. For me personally, I see a potential ecosystem enabled by this spec. Knowing I could access tooling by adhering to spec can be compelling.

I'm sure there's more but here's the prior art I'm aware of:

• Theo
  • Predictable Spec, easy to build tooling for
  • Doesn't support arrays or nesting
• Style Dictionary
  • Supports nesting, not arrays
  • Supports aliasing

OK, I'll stop now 😝. I hope some of that is helpful in continuing this discussion.

[jxnblk]

Thanks @timhudson! This is super helpful!

1. Static definitions JSON/YML

I agree that having a statically defined theme for this spec makes a lot of sense. Personally, I'd rather avoid inventing anything like the templating in Style Dictionary – I think that can be handled by whatever generates the theme object if needed.

2. Functions as values

I think similarly, functions could be used to generate the object, but I don't think this spec has to deal with templates or functions at all. How the scales are defined should be outside of the scope here, IMO

3. Abstracting away platform specific language/concepts

This point I probably disagree with. While other specs may try to "bridge-the-gap" across platforms, I don't think that should be a goal here. CSS is a fine spec, and I'd rather this theme specification build on top of that base (because I think it's good). For a lot of this, it's not too difficult to translate from web terms into proprietary platform terms or ignore parts like media queries where it isn't applicable.

4. Prior art

Yes, prior art absolutely should be documented in this project somewhere. Until I proposed this, I'd never heard of Style Dictionary, and I do mention Design Tokens (which is what the Theo implementation is based on IIRC)in my blog post. If there are any others, please feel free to open a PR to include them.

[timhudson]

functions could be used to generate the object, but I don't think this spec has to deal with templates or functions at all

I've been thinking a lot about dynamic theme modification lately, such as mobile sizes or high-contrast colors, but I've mostly thought of this as something acting on static tokens. I really like your suggestion above. It's a good mental model and maybe worth documenting for anyone else attempting to find where dynamic theming can fit in with static theme definitions.

CSS is a fine spec, and I'd rather this theme specification build on top of that base (because I think it's good)

I agree. I'm not concerned with using, or even favoring, CSS terminology. It's familiar, stable and in-line with typical design tokens.

I'm more thinking about the concepts that don't port well to other platforms. Rather than single out any one example, it may be better to map out my thought process as I evaluate some of these keys:

Is the key…

1. a commonly used term (colors) or visual concept (shadows)?
2. broadly useful (space) or fundamental to visual systems (fontSize)?
3. well, thats all I got. Ha!

it's not too difficult to translate from web terms into proprietary platform terms or ignore parts like media queries where it isn't applicable

I'm particularly interested in translation and portability. This is mostly where I'm coming from.

Regarding ignoring parts of the spec, the question I'm inclined to consider is how often or in how many contexts would folks ignore this key? If this number felt low, I would begin to ponder that keys value and the specs increased surface area.

My feedback above isn't really actionable right now as it's focused more on thinking than actual output. But hopefully that is within the nature of this issue.