docs: add section on token definition structure

[hbuchel]

Description of changes

We don't have an explicit structure defined for creating component tokens for the web and there are a couple different patterns used throughout our components, currently. We should have this defined so that contributors know how to structure a component's tokens to be consistent with those already defined, and so that users of the tokens have a consistent way to discover what tokens are available.

After a brief chat with @dbanksdesign this is the proposal:

component[variant][state][child]

I included a pseudo-code version of what that looks like in practice in this PR for updating the Theming docs.

This allows us to keep each definition type grouped. This means you could readily find all of a particular state's tokens for a variation without hunting through nested child objects. That is:

export const component = {
  childA: { /* tokens */ },
  childB: { /* tokens */ },
  _focus: {
    childA: { /* tokens */ },
    childB: { /* tokens */ }
  },
  large: {
    childA: { /* tokens */ },
    childB: { /* tokens */ },
    _focus: {
      childA: { /* tokens */ },
      childB: { /* tokens */ },
    }
  }
}

As opposed to:

export const component = {
  childA: {
    /* tokens */
    _focus: { /* tokens */ }
  },
  childB: {
    /* tokens */
    _focus: { /* tokens */}
  },
  large: {
    childA: {
      /* tokens */
      _focus: { /* tokens */ }
    },
    childB: {
      /* tokens */
      _focus: { /* tokens */}
    },
  }
}

These are simple examples, but for larger components that have many child elements and tokens, the second version might require a little more sleuthing around the file to find all of the affected, in this example, focus styles for a component.

Really, the most important part is aligning on one format so that developers know how to proceed when making new definitions, and so users can have a consistent reading and discoverability experience for the token files.

This also calls out the use of an underscore prefix for defining state tokens, which helps with quickly distinguishing a state from a variation name. That is, we should do:

_focus: {},
_hover: {},
_disabled: {},

and not

focus: {},
hover: {},
disabled: {},

Open Question

• Is this the best place for this to live, on the Theming overview page? The Theming section in our docs is aimed more at the consumers of the library; while this information is a little more aimed at developers who want to contribute to Amplify UI itself. I could see where it's useful for consumers, though, as it's nice to know what to look for when learning what tokens are available.

Issue #, if available

N/A

Description of how you validated changes

Tested in local docs instance.

Checklist

• PR description included
• yarn test passes
• Relevant documentation is changed or added (and PR referenced)

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[changeset-bot]

⚠️ No Changeset found

Latest commit: f68eaa4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[reesscot]

Feels like it might be more useful if we provide a real example from the codebase?

[hbuchel]

+1, will update.

[hbuchel]

Updated to include an abridged example (didn't want to include the whole file) from the Button component.

[reesscot]

I like the proposal, just had some comments on aiming it more towards users of the theme, rather than contributors. Users do have to know how to reach specific component tokens if they want to define their own theme.

[dbanksdesign]

Looks good, just one question from me and I like Scott's idea for a more concrete example.

[dbanksdesign]

Should we change [variant] to [modifier]? Some components have a variant prop as well as a size prop

[hbuchel]

That works for me; maybe a little more inclusive of both variants (primary, link, etc.) and size.

[hbuchel]

Updated to include this change, and added some definitions for those terms (modifier, state).