PAL and Carbon audit of indexed components

[kingtraceyj]

We need to audit IBM Products PAL to better understand why components are being indexed they way that they are. Many subcomponents are not a part of the IA and many overarching patterns are only in storybook as a series of subcomponents.

We should also look through current Carbon storybook and compare how Carbon core indexes components verses IBM products.

How are teams classifying assets? What are the relationships (Variants, siblings, assets built from other assets)?

This audit can inform best practices and our next steps in coming up with a design solution.

Overall problem:
Currently, Carbon and PAL component documentation can contain multiple components in one page. Not having a one to one relationship can create confusion when comparing the storybook components with the website components. In Carbon next, some components will not have documentation or the documentation is housed in a different documentation and cannot be found.

Figma: https://www.figma.com/file/YY6mTzBIiNp5JuCgfh2QTf/Documentation?node-id=2%3A649

[kingtraceyj]

from anna:

Sub-components: (child component?, nested component?)

• components only on the code side which have restricted usage and can only be used in tandem with parent component.
• Example: Accordion item (child component), Accordion (parent component)

Variants:

• different types of a single component
• Example: code snippet (component), inline, single line, multi-line (variants)

Styles of components:

• Components that share 1:1 functionality but have different visual styling
• Examples: Fixed and Fluid inputs

Component:

• Schema definition: Building blocks that have been designed and coded to solve a specific user interface problem.

Closely related component group:

• separate components that share the same parts or the same functionality or usage.
• Example: Dropdown (component), Combo-box (component), Multi-select dropdown (component)

Compound component:

• A combination of multiple components and possible custom parts that create a larger multi-function components
• Some existing components might actually be compound components (data table, pagination, modal)
• Example: Text toolbar

Pattern:

• Schema definition: Best practice solution for how a user achieves a goal through reusable combinations of components and content with sequences and flows which are too complex to be encapsulated in a single component.

Workflows:
Potentially something bigger than a pattern, spans across multiple pages, experiences? (tjk: this work is closely related to the work the practices team is doing: https://app.mural.co/invitation/mural/ibm14/1660581517517?sender=traceyking&key=c9e4fe43-f0c5-4c32-bc96-101295ffef07)

[aubrey-oneal]

Case studies (a mini audit that captures the main structural problems we are facing):
https://www.figma.com/file/VtB7s2EV9CMUNs0Uag9RYw/Variants-and-Patterns

Josh's previous research: carbon-design-system/carbon#9623

Next steps:

• talk to devs on logic of some storybook examples. Perhaps change storybook language from component to pattern. May need to better define pattern. (closes this issue)
• we want some sort of logic tree to scale our decision. This includes defining the cutoff for being a variant, component, and pattern. Storybook/Docs discrepancy logic exploration #1360
• Play around with usage tabs for Option 1 to help us see if there is redundancy. Visual Exploration for Docs/Storybook asset discrepancies #1357

[aubrey-oneal]

Conclusions:

After sharing our findings and learning about storybook IA from Taylor and TJ, we know that the logic tree #1360 will need to include a combination of options 1 and 2. We also want to explore the structure of Abstract grouping > Component sets > components > variants.