Should composites be part of the MVP specification?

dbanksdesign commented 3 years ago

If so, which composites should be included initially?

border
transition
shadow
gradient
text style
color pair

border-radius

Different radius per corner. So if a company has a brand thingy with one corner more or less rounded this would be important (see google material design )

transitions

combines timing, delay and easing curves

spacing / padding

You may want to make sure that an element has the correct spacing on all 4 sides and the spacing is normally connected

kevinmpowell commented 3 years ago

@lukasoppermann I like the three you mentioned, though they all seem to align with CSS shorthand properties. Do you know if those same groupings exist on iOS and android platforms?

lukasoppermann commented 3 years ago

Hey @kevinmpowell, sadly I don't know this. My iOS and Android colleagues don't use padding / spacing tokens. On those platforms many advanced layout functionalities don't accept tokens.

However, it seems that border-radius on iOS uses the same logic: https://developer.apple.com/documentation/tvml/border-radius Android seems to also support this: https://developer.android.com/reference/android/view/RoundedCorner

For transitions I can't tell you this either. But it looks like some of the values are similar: https://developer.apple.com/documentation/uikit/uipercentdriveninteractivetransition/1622048-completioncurve

gossi commented 3 years ago

I think composite styles are quite powerful and should ship immediately. If not the community will get creative in shipping their own formats on top. Given the way, they are designed they allow for any combination, which makes them super powerful. I believe this way, a set of commonly used type definitions will probably find their way into an almost standard npm package at some point?

To me would make sense to get the typedefs robust and this is the thing that will be part of the mvp. Initial types you mentioned, they should come as a npm package or so. That is to give them space for experimentation with the typedef API. That also gives the opportunity to make the first batch of typedefs solid/proven. Once that is the case, promote them to become types as part of the spec.

rfrey-rbx commented 3 years ago

I find color pairs powerful, particularly for enabling developer tooling for accessibility such as contrast checking.

A current typedef I'm using for fg/bg color pair tokens is specific to the naming and tooling in our system e.g. { Color: color, OverSurface: color, ForText: boolean }. ForText is used to render the token as "Aa" over the OverSurface color instead of just a colored dot.

If no composite types are included in the spec then in our case we'd probably be waiting for a tool vendor like Figma (or a well integrated plugin) to adopt the spec and implement their own specific typedef for color pairs and then either have an automated translation between our typedef and theirs or adapt our typedef in source to match theirs.

The motivating factor to translate or adapt would be better display and selection of tokens within their interface.

Being outside the javascript ecosystem we'd be implementing the generated docs and consumer code ourselves in lua so wouldn't be as influenced by a community npm package.

Text styles are also something that I typically author, display, and consume as bundle of tokens, so add a +1 to including that if there are any composites defs that get added to the spec.

kevinmpowell commented 3 years ago

This part of the spec needs more definition. Defining what composites should and shouldn't be used for with a lot more examples.

I view a composite token as a set of additive design decisions applied to a single element. So border, transition, text styles, shadows, (any css shorthand property basically).

What gives me pause are mutually exclusive sets of values. @rfrey-rbx's mention of color pairs doesn't fit as a composite to me, I'll try to articulate why.

I think it's because there's additional information required to correctly apply those values like the specific keys of Color, OverSurface and ForText. Those feel very system-specific and too bespoke for us to bake into the spec.

I have similar hesitation when I hear of light/dark mode color sets as composites or responsive font sizes for different viewports. In all those cases there's implementation-specific information required to apply the correct token at the correct time and I see implementation details starting to drift into the tokens file itself, which makes it harder to standardize.

In my view a tokens file should not contain any context-specific implementation hooks or keys that trigger automatic switching between tokens or automatic application of tokens.

ChucKN0risK commented 3 years ago

I also think we also should define more precisely which composite we'll support by default.

I consider the following ones essential:

border
transition
shadow
gradient
text style
transition

I don't think border-radii, spacing/padding and color-pair should be part of the spec. Let me explain why.

Border-radii can differ from one angle to another in CSS. But if it's not the case in iOS and in Android then I think we should let people create as many radii they need to fix this gap. I tend to see our composite tokens as an agnostic base of token that could be created whatever the platform. I'm interested to have your input on this @lukasoppermann ;)

Spacing/padding I don't understand why those are necessary as we already provide a "dimension" type. I also don't know if you can define such properties in iOS and Android. I'm interested to have your input on this @lukasoppermann ;)

Color-pair While I understand why this combination is useful, I think it's still a "hack" to check a11y color contrasts. This should be doable but not included as a default composite type in the spec.

ChucKN0risK commented 2 years ago

Reviewed by the spec editors on 2021-11-16.

Decision We decided to remove user defined composite types.

Why? This enables the spec:

be more easily implemented by design tool vendors
be more easily understood by users as those predefined types are part of the "common" language people already have

Action to be taken We'll be adding some predefined composite types:

border
transition
shadow
gradient
text style

Those composite type will ease the adoption of the spec whether it's by tool vendors or by users.

To create those predefined composite types we'll add more token types in the spec.

ilikescience commented 2 years ago

I know I'm a bit out of the loop on the conversation, but I'd love to keep digging on why composite types need to be further defined at all, whether by a user (in user-defined composite types) or by the spec (in predefined composite types).

To take a common use case, for example, say I define a composite token for a type style:

{ "display-large" : {
    "type": "composite",
    "description": "The largest heading",
    "value": {
        "font":  {
            "type": "string",
            "value": "Roboto Regular"
        }, {
        "size": {
            "type": "number",
            "value": "57"
        }
    }
}

Is there a benefit to having some further definition? My first thought is that it might give a parser some hints as to what the end user will do with those tokens, but I imagine that the same could be accomplished by inferring the use case from the contents.

design-tokens / community-group