[Design Token] - Semantic Colors

[mmailaender]

Describe what feature you'd like. Pseudo-code, mockups, or screenshots of similar solutions are encouraged!

Skeleton uses a color palette design system consisting of values from 100 to 900:
https://www.skeleton.dev/elements/tokens
https://www.skeleton.dev/docs/generator

--on-primary: 0 0 0;
--color-primary-50: 219 245 236; 
--color-primary-100: 207 241 230; 
--color-primary-200: 195 238 224;
...

Instead, I would like to bring up Sematic Color Design Tokens.

--color-background-primary
--color-background-primary-faded
--color-border-primary
--color-border-primary-faded
--color-foreground-primary

This approach is more aware of the context (like background, border, foreground), making it easier for the user to achieve consistent theming throughout the app.

What type of pull request would this be?

Enhancement

Any links to similar examples or other references we should review?

https://reshaped.so/content/docs/tokens/color

[Sarenor]

There's 2 problems with that:

1. Bit late to change such a fundamental system during the first release candidate
2. https://www.skeleton.dev/blog/deep-dive-skeleton-styling -> Color Pairings
   Skeleton is explicitly designed for and around the numeric color pairings to achieve easy, turn-key and good looking dark mode.

This approach is more aware of the context (like background, border, foreground), making it easier for the user to achieve consistent theming throughout the app.

In a simple, perfect world where you don't want or need to much customization, Skeleton should already handle that for you.
You only need to interact with the css variables when introducing new, specialized components that your app/design needs and it makes sense to have you handle the specific color pairings or just colors for those because Skeleton can't make assumptions about them.

I'd be curious what your problem with the current design system is and where you feel it hinders you in a way that makes you want a more context-aware or in my opinion context-assigning system, if you'd care to elaborate.

[mmailaender]

I think what you're saying regarding the default components makes sense. Based on that, I would say that the documentation confuses me a bit:

You're explaining here that the "recommended manner of styling most components" is background, text, border with numeric colors:

<ExampleComponent background="bg-secondary-500" text="text-yellow-500 md:text-green-500">Skeleton</ExampleComponent>

But in the components, I mostly found the Variants styling approach you probably referenced in your post. So it feels that the Variants are the "recommended manner to style most components".

I realized the Variant concept for the first time in the Components, but not once in one of the many styling, colors, etc. docs before.

The Variant concept feels simple to learn/adapt and should help with consistency in most cases, as you already mentioned. If I want to go beyond that, having a numeric system could be beneficial because it gives me more flexibility.

That brings me probably to the main problem of my confusion and why I suggested the enhancement: A lot of documents talk about the color design tokens (too much noise) and in different ways:

Theme Generator
https://www.skeleton.dev/docs/generator
Styling
https://www.skeleton.dev/docs/styling
Colors
https://www.skeleton.dev/docs/colors
Design Tokens
https://www.skeleton.dev/elements/tokens
Components
https://www.skeleton.dev/elements/buttons
https://www.skeleton.dev/elements/cards
https://www.skeleton.dev/elements/alerts

Streamlining this into a "80% of your use cases" and "The full flexibility and extensibility" section could eventually help to navigate a new user through the docs while keeping an easy-to-take learning curve.

[Sarenor]

That's excellent feedback for the currently ongoing documentation overhaul: #783
Let me get that noted down over there!

[endigo9740]

I would like to bring up Semantic Color Design Tokens.

This has come up in the past, unfortunately it's not a feature request but a whole new library. It completely invalidates and removes the majority of the mechanisms for how Skeleton operates. I understand there's a place for this, but it's not in Skeleton.

You're explaining here that the "recommended manner of styling most components" is background, text, border with numeric colors:

FYI we're in the midst of some documentation updates and I think the wording for this will need to change. This is now the recommended method for OVERRIDING styles locally. If you need a one-off change, this is a simple way to do that. If you need global/sweeping changes our recommended approach is to use our Selector classes and use global stylesheet overrides, per:
https://www.skeleton.dev/blog/deep-dive-skeleton-styling

But in the components, I mostly found the Variants styling approach you probably referenced in your post. So it feels that the Variants are the "recommended manner to style most components".
I realized the Variant concept for the first time in the Components, but not once in one of the many styling, colors, etc. docs before.
The Variant concept feels simple to learn/adapt and should help with consistency in most cases, as you already mentioned. If I want to go beyond that, having a numeric system could be beneficial because it gives me more flexibility.

Variants are a rather late addition to the library, so they're not quite featured as prominently. I agree though, they're quite useful and should get more attention. This will be changing soon, with them receiving their own dedicated documentation page alongside design tokens before the next release.

That brings me probably to the main problem of my confusion and why I suggested the enhancement: A lot of documents talk about the color design tokens (too much noise) and in different ways:

Very strange choice of words here - one of the most critical and useful features of the library is noise? I'm sorry but unless I'm misunderstanding you that's objectively wrong. I might suggest watching the video we shared by Brad Frost that explains what design token are and perhaps lean more about how they operate:
https://vimeo.com/showcase/9653752/video/724689965

The features and mechanism of Skeleton come from a real need and satisfy real problems. It's ok if Skeleton isn't working the way you personally want it, but I can't help but feel our goals and your goals aren't quite aligned here. And again that's fine. If Skeleton doesn't operate the way you want it you have a few options:

1. Look into alternative libraries - Svelte-specific options are limited, but framework agnostic options are plentiful
2. Consider building your own library from the ground up - that way it operates exactly as you would like. I can tell you personally it's a lot of work, but it's very satisfying
3. Tap that "fork" button at the top-right and go in whatever direction you want with the library. Skeleton is MIT licensed and open source, so that is an option you possess.

Thanks for your time and input. Unfortunately there's very little actionable here that aligns with the project goals. If you wish to continue this conversation please create either a GitHub Discussion or reach out on Discord.

[mmailaender]

@endigo9740, maybe we have a miscommunication here.
I'm pretty familiar with Design Systems and Design Tokens and strongly follow these principles in my products.

If I'm talking about too much "noise", then I mean that your current state of documentation was hard for me to understand because skeleton has a lot of pages that talk about the same stuff in different ways (Different ways = harder to learn/understand). (See the links that I shared) At least I have the feeling because I'm new to Skeleton. So my whole point was about: Preciser Docs

My initial suggestion was to replace the numeric with a semantic system. Why? I worked with both and found that semantics is simpler to use while covering most use cases. Nevertheless, as Sarenor already pinpointed: You also have a simplification called Variants. That is solving my primary motivation, why I brought up semantic colors. But as I also already said, following the concept was hard for me. And that's the reason why I shared my feedback with you:

Streamlining and focusing the colors/design tokens documentation into "80% of your use cases" (Variants) and "The full flexibility and extensibility" (numeric system) section => helping new users (like me) to navigate through the docs while keeping an easy-to-take learning curve.<<

So I really hope that the first part of our conversation was simply a misunderstanding and this is resolving the "Very strange choice of words" offense.

[endigo9740]

If I'm talking about too much "noise", then I mean that your current state of documentation was hard for me to understand because skeleton has a lot of pages that talk about the same stuff in different ways (Different ways = harder to learn/understand). (See the links that I shared) At least I have the feeling because I'm new to Skeleton. So my whole point was about: Preciser Docs

Hey I get it. That's why our current and ongoing focus is improvements to our documentation. It's the last major hurdle before we consider this production ready. We've been building up the the current docs over the course of a year and in that time you're going to have creeping issues, inconsistently, and mismatched tone and direction. There's just no avoiding it in a project of this scope and scale. But this is exactly what we're aiming to improve here:

• Documentation Updates #783

To catch you up - we have a few technical prerequisites before we begin our content-focused improvements, which are slated to begin next week. I'll be generating a general guidelines for technical changes (migrate to the preview component, make sure prop values are accurate, etc) while also providing recommendations in terms of tone in order to provide a more consistent voice. Then we have a number of volunteers that will help implement this.

I'll be personally overseeing the updates to the "Docs" section of Skeleton, which covers critical areas such as the introduction, onboarding, and educating our users on what Skeleton is and how to take advantage of it's full feature set. Keep in mind not every feature currently present was available a year ago - which is why there's gaps and inconsistently in direction. We can only address this now that we have the entire roster of features in front of us.

My initial suggestion was to replace the numeric with a semantic system. Why? I worked with both and found that semantics is simpler to use while covering most use cases.

The thing you have to understand here is you're coming in at the 11th hour and suggesting a change that is widely out of scope for our current project and goals. I'm sure you mean well, but I've worked with systems that operate like this (ex: Angular Material) and it was was awful. It's limited and restrictive in ways many folks won't recognize until it's too late. Skeleton was purpose built to go down a different path. Additionally, this is not a trivial change in direction - this is a completely different approach to the foundation of the library and it's core tenants. To speak plainly here, it's highly unlikely to ever happen.

Given this, the summary here is you're suggesting changes we're already aware of and in progress making, as well as a suggestion that does not align the the goals of our project. Hopefully that clears up any miscommunication on your end.

Again I'd advise this discussion continue in another location - this isn't the place for this kind of discourse.