Design Token Compatibility

[roblevintennis]

I can see a world where design tokens that meet the spec can be used and then transformed into the OP .js definitions. But, I see the other way around too; that is, you can work in css custom properties which feel more natural for most FE devs (I think), but then generate design tokens.

The benefit would be interoperability. Perhaps there's tooling that could eventually sync with FIgma or Sketch so your updates on both sides synchronize.

[argyleink]

related #21

currently, for better or worse, the props source is JS and the CSS files are generated. only time will tell if that was the right path. was easier for me to import js from js and then write a css file. but i bet there's easier ways.

[roblevintennis]

Gotcha. Ok, this is probably a longer term idea and possibly one better solved by combining a few tools (or waiting to see what sprouts up)...thanks for hearing my idea. Feel free to close it out (I know too many issues / discussions can distract haha)

I don't see a way for me to close it

[argyleink]

Maybe this is closer to what you were thinking? https://www.knapsack.cloud/figma-designsystem

I think there's even a design token standard.. I didn't really check to see how compliant I was.. might help with this interop story you're mentioning?

[roblevintennis]

I listen to their podcast and have been aware of Knapsack but have never actually seen it or know how it works exactly. But from what I understand, yah, this is the sort of setup where design tools and code start to synchronize. I saw another tool like this emerging that I cannot remember the name of.

---

But, I was more referring to the community for design tokens themselves:
https://www.w3.org/community/design-tokens/

I joined as a fly on the wall but haven't really kept up so much but it looks like it's still early in terms of an actual officially blessed design tokens standard but here are some resources:

https://design-tokens.github.io/community-group/format/#file-format

And here's a pretty good example of JSON being transformed to sass variables:
https://design-tokens.github.io/community-group/format/#export-tools

To my mind, it seems likely they'll go with JSON, will use value and other likely properties, etc. Also, with the big players involved I presume some very robust parsers and transformational tooling will emerge (if it hasn't already and I'm not aware). Also, this standard could change.

---

Idea

So in terms of OP, it might be nice if the .js file were:

• converted to JSON
• the parser updated to spit out css custom properties in the way the w3c example above does (each level of the JSON down to value just gets added to the hyphenated variable name resulting in something like --foo-bar-baz where baz hit a value JSON key.

Above would be the conceptual ideal I'm thinking of. But it also contributes some potentially breaking API issues for OP since it's opted for flatter less verbose names (which I totally can relate to in terms of readability):

:where(html) {
  --lime-0: #f4fce3;
  --lime-1: #e9fac8;
...
}

So if you literally took every key of JSON from

{
	"op": {
		"color": {
			"lime-0": {
				"value": "#f4fce3"
			},
			"lime-1": {
				"value": "#e9fac8"
			}
		},
		"typeface": {
			"whatever-we-call-typography": {
				"value": "Comic Sans MS"
			},
		}
	}
}

you'd get --op-color-lime-0: #f4fce3; which breaks the API (bad).

Now, and this gets into the weeds in terms of whether it would conform to this upcoming design token standard interoperability wise , but, you could seed the crawler with start points e..g ("I'd like these categories built": ["op.color", "op.typeface"] and placed maybe into their own files with the final result maintaining the api so: --lime-0: #f4fce3 and put in src/props.colors.css as you already have it).

Flaws

Would 3rd party parsers have the same interpretation from the JSON alone and produce the same meaningful results on the other end? Probably not. I'd say this is a risky approach in terms of maintaining potential interoperability. These "start points" would also add complexity of the code itself with little gains…

Better way

So, because the standard isn't finalized, and also https://design-tokens.github.io/community-group/format/#export-tools clearly shows every key getting transformed literally into the sass variable name e.g. --op-color-lime-0, it might be least risky and simplest to just go ahead and start out with the JSON denormalized and flat to actually depict the OP API. So you'd just go with an accurate representation of OP in their own files. So, literally you'd have src/props.colors.lime.json with:

{
	"lime-0": {
		"value": "#f4fce3"
	},
	"lime-1": {
		"value": "#e9fac8"
	}
}

So instead of the one colors.js files with various exports as you have today:

export const Red = {...}
export const Lime = {
  '--lime-0': '#f4fce3',
...
}

I think these each color would become its own separate file props.colors.lime.json, props.colors.red.json, and so on.

I think this will scale with the standard and emerging tooling (unless they completely change their direction drastically of course!), and, the file names themselves do fine in acting as a form of categorization for the time being; e.g. props.colors.lime.json is obviously the file with design tokens for colors, variant of lime (props.category.variant.json)—really, in a similar spirt as you've already done with the .js files. Not sure if the props. is actually necessary (colors.lime.json, colors.red.json would seem more potent to me), but I don't have a strong opinion and can leave props if you feel strongly about it (let me know).

Misc JSON properties

It seems in order to make this helpful, we'd want to sprinkle in things like https://design-tokens.github.io/community-group/format/#dimension for things like props.sizes.css so that other tools can utilize that. The OP transformations would probably use that to know whether to quote the property or not e.g. --size-000: -.5rem; and not --size-000: "-.5rem"; which would of course be wrong. They also go into additional-types and that smells of ongoing change. For now, OP's transformer would only care if the value is quoted or not. So we'd only support basic types like number and what not. If no type is supplied for a particular token, quoting its value is assumed.

---

might help with this interop story you're mentioning?

I think you were referring to Knapsack. But are you looking for help and/or interested in this for OP? If so I could possibly help with disclaimer that I'll likely not be the fastest in terms of turn around with a job, family, and my own OS library to contend with but willing to give it a stab.

Approach

Honestly, I would try to leverage the create props looping approach you already have and only make it good enough to work as a stand in. I'm 99% sure, a big player will make an extremely robust and better tool for this if they haven't already. So the goal would be to have a parity result in terms of a final props.thing.css that you already have with no accounting for robustness. I suppose a nice verification test would be "color file produced from JSON === color file from JS" maybe even just have specs that produce two md5s and ensure their the same or something.

I suppose the :where(html) bit could be built into the transformer as a sort of prefix since it won't need to be in the design tokens themselves

If you're fine with this disclaimer I can give it a go in my spare cycled :-) Lmk

[roblevintennis]

Now that you've pointed this out, I can't believe I forgot about these tools! I remember Theo or Theo8 from SalesForce did some of this too.

For Style Dictionary -- https://bootcamp.uxdesign.cc/keeping-it-consistent-design-tokens-eaecdbdfee50 shows nice examples.

https://diez.org/ too

And I don't know what these guys are using under the hood to generate, but look at the list of formats they make available derived from design tokens:
https://www.duetds.com/tokens/#list-of-all-available-formats

Perhaps a tool like OP would want to decide if things like animations CSS, and gradient CSS is really a token or not, and possibly continue to just keep those in JavaScript and then things like sizes, colors, etc., get ported to design tokens. Or of course OP could decide not to do design tokens at all for now too 😄

[roblevintennis]

Looks like SD is winning according to npm trends:
https://www.npmtrends.com/diez-vs-style-dictionary-vs-theo

[roblevintennis]

@airen I refactored AgnosticUI this morning to use SD; wow, so easy! AgnosticUI is a set of monorepo workspace packages, and the agnostic-css package houses all CSS for framework implementations (react, vue 3, svelte, angular). So, the CSS framework now pretty much derives all the common custom properties styles from design tokens:

https://github.com/AgnosticUI/agnosticui/tree/master/agnostic-css

Thanks for pointing me to forgotten Style Dictionary!

@argyleink I'm not sure if this is helpful in terms of comparing contrasting to deriving from JavaScript and/or if you would consider completely moving from JavaScript source to JSON, but I can vouch that it was and would be quite a painless process. I just don't know about the multiline and gradients 😄

[argyleink]

I don't think I'll be moving the source to JSON, but I'm open to having some (as many as make sense) props consumable as JSON.

[roblevintennis]

Sounds good @argyleink 👍🏽

[roblevintennis]

Having second thoughts after contemplating this -- I think some sort of AST approach is going to scale better then the approach I listed above which would likely be fraught with bugs.

Unfortunately, AST's are a bit out of my wheelhouse and not something I have bandwidth to sign up for learning and implementing myself. That said, there are folks "out there" that probably already have some experience transpiiling with Acorn / Babel or maybe there's an npm package resource like https://github.com/vtrushin/json-to-ast (I saw several json to ast parsers), and they'd probably be able to pull this sort of thing off.

Above said, I do think longer term, having OP use standards based design tokens will have benefits. I just don't know how to recommend implementing it practically at this point.

---

I've asked the design token community if such tooling is evolving in-the-open and if it's available or if there's a list. We'll see what they say.

[airen]

I can see a world where design tokens that meet the spec can be used and then transformed into the OP .js definitions. But, I see the other way around too; that is, you can work in css custom properties which feel more natural for most FE devs (I think), but then generate design tokens.

The benefit would be interoperability. Perhaps there's tooling that could eventually sync with FIgma or Sketch so your updates on both sides synchronize.

I also had this idea of adding Design Token designs to component-level props. I just posted an issues on this. #93

[argyleink]

Nice, I'm mostly hearing "it'd be sweet if there was json to use." Which totally! We're making css files, why not make json files with very similar loops. I'm all for outputting json, it'll serve from the CDN nicely too.

are there multiple json formats to try and conform to?
you're down to take this on?

[argyleink]

see #97 🙁
kicked off the generation of tokens there! hopefully takes a chunk of time/work off this for ya!

i can already foresee some issues tho, like the adaptive shadows and stuff, but it also looks like the design tokens standards have ways to create associations and other stuff. it does, to me, seem to be a big undertaking AND we're trying to take "web specifically created tokens" to a world where "design tokens rain down into android, ios, etc, where web centric tokens may not translate."

there's gotta be some middle ground tho. like the colors and stuff can totally ship and be importable as json. but easings for example, those just dont travel straight up, nor the animations or gradients. we'll have to navigate this and found out what's meaningful to turn into "design tokens for wider design token world" and be aware that Open Props is CSS / web first.

[airen]

I've been doing Design token related stuff recently, and my main task is to provide different variable parameters for components based on Design token to automatically generate more UI styles. I think it's very similar to the ideas mentioned here, and I hope to do something meaningful about it.

[roblevintennis]

Wow, you're fast @argyleink 😝

Yes, I mentioned I wasn't sure how some of those things would translate to tokens. Sounds like they aren't.

But, maybe they, in fact, are NOT tokens! If gradients, easings, and animations types of values just don't make sense you could also just leave those out of design tokens world which is probably consistent with the whole idea of design tokens anyway. Maybe what you've started on that PR is a good first approach, then you can do a "help wanted" for the more exotic types and someone really motivated will tackle that for you. It sounds like @airen is interested possibly, but I'm sure there's going to be someone who will be motivated enough to come with some creative genius token solution for those others.

It IS interesting to see if they make it easier to represent multiline string templates and the other things you've mentioned. Might be worth pinging the working group I dunnno...maybe they could use OP as a sort of test bed then you'd get it all done for free mwa-ha-ha-ha!

[roblevintennis]

Update: https://github.com/argyleink/open-props/pull/97/files#r762419427 points out the overarching issue I'm seeing with keeping JS as source of truth. With JSON design tokens you get bi-directionality, with JS it's one-way and OP would always need to drive any value updates (as opposed to letting a designer update values in Figma et al, and then export a new token set that OP utilizes).

[roblevintennis]

For more complex values I'm wondering if things like https://design-tokens.github.io/community-group/format/#extensions will help there.

[argyleink]

Shipped in v1.0.12 at https://unpkg.com/open-props/open-props.tokens.json following the web design token spec draft

[roblevintennis]

Believe it or not, I'm new to using these discussions so I probably don't know what I'm doing -- I would mark this as "accepted" or something if I saw a way to (but maybe that's for you to do?).

Anyways, congrats are in order 🎉 🙌

[argyleink]

yay! it's a great addition, thanks for chatting it all out and sharing thoughts 🙂

i think since this discussion is an idea, it cant be marked resolved? anway, glad it's in!

[roblevintennis]

Haha it never goes away!! Yeah...good stuff 💯👍🏽