Document "Appearance" values and how they can be changed

edhgoose commented 2 months ago

Please list the related package(s)

checkout-ui-extensions

If this related to specific APIs or components, please list them here

I was specifically looking at the Icon appearance (https://shopify.dev/docs/api/checkout-ui-extensions/unstable/components/media/icon#iconprops-propertydetail-appearance), but I think anywhere where "Appearance" is defined would be helpful.

Is your feature request related to a problem? Please describe.

I'm new to Shopify and my first foray into building anything on Shopify is via Checkout Extensions.

I'm finding the "Appearance" property very confusing. While some are fairly obvious (e.g. success, critical), and seem to have obvious results (green/red respectively), I find the others quite bewildering.

For instance, an extension of ours has the following snippet:

<Icon appearance="accent" source="discount" />

On my test store, using different values (e.g. swapping accent to decorative) seems to give different values, but for our a client they're finding that's not the case.

I'm struggling to identify what colours I'm supposed to be using and whether there's an obvious relationship between the values I put in these components and the colours they might choose somewhere else in the Shopify platform.

Describe the changes you are looking for

Some further guidance (even just a link somewhere) explaining the Appearance property and how the components work would be awesome.

Describe alternatives you’ve considered

I've had a look at the typescript code, and I've tried playing with my own test store, but I'm struggling to replicate the behaviour my client is having.

Additional context

jun-shop commented 2 months ago

We have some very basic documentation on how branding works with checkout - definitely agree though that "appearance" can be unintuitive as some of these values can have fallback experiences. They are all influenced by a merchant's branding so that is probably what you're seeing in terms of the difference between your test store and a client's. We've tried to keep the meanings as close to semantic as possible so rather than thinking of "red" vs "green" you should be thinking about what the underlying meaning is. (e.g., if a merchant decides to brand their "critical" color to be purple the critical icon will also be purple)

Very loosely for the more abstract ones:

accent is for links. It can be defined at a global level or in a color scheme that is then applied to a specific area like the header, order summary, etc.
decorative is a highlight that can be defined at a global level or in a color scheme - I believe by default it should be the same as base
subdued is a more subdued color that is derived from the base icon color
monochrome will take on the same color as the text surrounding it regardless of whether or not an icon color has been specified via branding

https://shopify.dev/docs/api/admin-graphql/unstable/objects/CheckoutBrandingColors https://shopify.dev/docs/apps/build/checkout/styling https://shopify.dev/docs/apps/build/checkout/styling/update-color-settings#step-2-configure-global-colors

jun-shop commented 2 months ago

Ah! also was told this exists: https://shopify.dev/docs/api/checkout-ui-extensions/2024-07/components/media/icon#appearance Will make sure this link gets added to our docs

edhgoose commented 2 months ago

Ah, thanks @jun-shop. That part at the bottom is helpful. Is it possible to reference that in the code somehow? Now you've pointed it out it's obvious, but I couldn't find it.

Also, is "decorative" not documented because it doesn't have any effect, or is that a mistake?

Shopify / ui-extensions