Variants

[mattrosno]

Summary

What problem (or opportunity) are we solving? Why are we solving it? Is there supporting user conversations or research?

The platform schema and indexing strategy has not yet accounted for component variants, and that has resulted in inconsistent indexing among libraries, and decomposed documentation when it's a better user experience to document like-components (a.k.a. variants) together.

Notification component example

https://next.carbondesignsystem.com/assets/components?q=notification - here you can see that Carbon Svelte and Carbon Vue indexed Inline notification and Toast notification separately, where Carbon React, Carbon Angular, and Carbon Vanilla has this indexed as Notification. All of those notification components inherit from the Carbon Core Notification. Since Carbon Svelte and Vue notification is indexed different from the rest, they can't inherit the Notification usage, style, and accessibility documentation like Carbon React, Angular, and Vanilla.

Create flows pattern example

Here you can see that the Create flows pattern is originally documented as one create pattern that has variations: https://pages.github.ibm.com/cdai-design/pal/patterns/creation-flows/usage. Those have been indexed as separate patterns: https://next.carbondesignsystem.com/assets/patterns?maintainer[]=ibm-products&q=create. Is that decomposition ideal? Would it be easier if all Create flow guidance was co-located in one pattern?

List example

The legacy site documents one List component with two variants: https://carbondesignsystem.com/components/list/usage/. Carbon React and Carbon Svelte have this indexed as Ordered list and Unordered list: https://next.carbondesignsystem.com/assets/components?q=ordered. As such, the those detail pages are missing usage, style, and accessibility documentation because the Carbon Core, Carbon Angular, Carbon Vue, and Carbon Vanilla index this component as List (not decomposed), for example: https://next.carbondesignsystem.com/libraries/carbon-styles/latest/assets/list

Theme component and function example

The Carbon React library has a Theme component and a useTheme hook (function):

• https://next.carbondesignsystem.com/assets/components?framework[]=react&q=theme
• https://next.carbondesignsystem.com/assets/functions?framework[]=react&q=theme&tags[]=hook

Yet, there's no need for these assets to have separate detail pages.

• https://next.carbondesignsystem.com/libraries/carbon-react/latest/assets/theme
• https://next.carbondesignsystem.com/libraries/carbon-react/latest/assets/use-theme

They should be documented together. The component and the hook are part of the same functionality to get and set the current color theme.

Job stories

What value will this deliver?

1. To do

Acceptance criteria

What requirements must be met to complete this request?

• [ ] Documented guidance on the definition of a variant, when variants should be documented, and how to document variants (e.g. table in overview page)
• [ ] Documented guidance on asset naming plurality (e.g. is it "Dropdown" or "Dropdowns"?)
• [ ] Documented guidance on how we're not indexing sub-components right now (e.g. "AccordionItem")
• [ ] Documented guidance on when to include multiple demoLinks

[mattrosno]

Right now, each indexed asset gets its own name, description, thumbnail, status, framework, etc. That's great for discovery, like Dropdown for example, where the catalogs actually index:

• Dropdown
• Combo box
• Multiselect

Ideally, those three assets are documented as variants of Dropdown, so there's one asset detail page that explains all three together.

Option 1 - redirect

We could add a redirect key to the asset schema, like:

assets:
  dropdown:
    name: Dropdown
    ....
  combo-box:
    name: Combo box
    redirect: dropdown
    ...
  multiselect:
    name: Multiselect
    redirect: dropdown
    ...

If an asset has a redirect key, then it wouldn't have detail pages. Instead, when you select one of those catalog items, it would take you to the specified destination (e.g. selecting Multiselect would take you to the Dropdown detail pages.)

We could have a display naming convention so the redirect destination is suffixed with (Name), e.g. combo box below:

Pros

• Flexibility on which variants can get top-level exposure
• You could see "redirect" assets in the catalogs and in library assets table

Cons

• Can't see status notes of redirect assets, because they don't have detail pages

Option 2 - canonicalization

Instead, we could index one of the assets as canonical and the non-canonical (a.k.a. variant) detail pages have duplicated content.

assets:
  dropdown:
    name: Dropdown
    docs:
      overviewPath: '/path/to/overview.mdx'
      usagePath: /path/to/usage.mdx
      stylePath: /path/to/style.mdx
      codePath: '/path/to/code.mdx'
      accessibilityPath: /path/to/accessibility.mdx
    ....
  combo-box:
    name: Combo box
    canonical: dropdown
    docs:
      $ref: '#/assets/dropdown/docs'
      overviewPath: '/path/to/overview.mdx'
      codePath: '/path/to/code.mdx'
    ...
  multiselect:
    name: Multiselect
    canonical: dropdown
    docs:
      $ref: '#/assets/dropdown/docs'
      overviewPath: '/path/to/overview.mdx'
      codePath: '/path/to/code.mdx'
    ...

In this example, the Dropdown asset has the full documentation that details usage, style, and accessibility guidance for all three variants, and that usage, style, and accessibility content is also used in Combo box and Multiselect assets.

The canonical key is just used for SEO purposes, so search engines know to just index the Dropdown pages, as the Combo box and Multiselect pages are mostly duplicate.

Pros

• Every asset found in catalogs and library asset tables get their own detail pages, so you can see everything like status notes
• This scales well, because what if we want to track usage metrics per asset, if each asset has its own maintainers, etc. By having separate detail pages, we can fully use the dashboard and overview pages.
• No need to have a variant switcher for dashboards, or dashboard roll-ups, etc.

Cons

• Will users be confused if the same guidance (e.g. which list to use) can be found in multiple places (in Ordered list asset and in Unordered list asset)? I'd argue no, because that guidance will already be duplicated so you can view it per JavaScript framework (e.g. Carbon React library, Unordered list component, usage page and Carbon Angular library, Unordered list component, usage page).

[mattrosno]

Recommendation:

1. Prerequisite: schema v2 to support asset $refs
2. Option 2 above so assets can share docs
3. Add related to assets schema, so each overview can have a table (or resource cards) that link to other assets (e.g. link to variants, or if it's a pattern link to the components used in that pattern)
4. Variants table in usage docs so we have the ability to document variants that might not be indexed as assets

With UX enhancements:

1. Update asset page breadcrumb to be based on its library, not asset type (catalog)
2. Include thumbnail in asset page lead space