From 348a6c49e9f008a3833ef9113269178a8b7a678d Mon Sep 17 00:00:00 2001 From: Anna Gonzales Date: Fri, 27 Sep 2024 15:07:06 -0500 Subject: [PATCH] Add: content edits --- .../component-checklist/index.mdx | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/src/pages/contributing/component-checklist/index.mdx b/src/pages/contributing/component-checklist/index.mdx index 272082ce782..9fcbccad00f 100644 --- a/src/pages/contributing/component-checklist/index.mdx +++ b/src/pages/contributing/component-checklist/index.mdx @@ -73,24 +73,24 @@ will be built and represented consistently across experiences. ## Code -In order for code to be stable, it must meet all of the following requirements. -Experimental code should plan for these requirements, but does not need to meet -them in the discovery or delivery phases. +In order for code to be stable, it must meet the requirements in the table below. +Preview code should plan for these requirements, but does not need to meet +them in the discovery or delivery phases. For additional guidance how we prefer to write code for the Carbon Design System, see the [Carbon Style Guide](https://github.com/carbon-design-system/carbon/blob/main/docs/style.md). | Requirement | Details | Why this matters | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **API guiding principles** | Prioritize end user: put the consumer/dev experience above how difficult it might be for us to implement. Interoperability: support wide band coverage of multiple react versions, node LTS versions, etc. Prefer framework/library agnostic approaches to component APIs and designs.Stability: always deprecate before removal, ensure long deprecation periods, consider the migration experience for developers. Composition: components should be broken down into logical pieces to support the many disparate configurations that are required by the business. Developer Experience: consider how a developer will use this component; will they find it approachable, confusing, complex, too simple? | Careful consideration of API design ensures that future changes to the system can be made in an iterative way that minimize disruption. Developer experience and productivity can be heavily influenced by confusing or needlessly complex APIs. The business has a wide range of requirements and should meet as many of them as possible. Prioritize the user wherever possible - if we can make things easier for them by writing extra code, handling complexity internally, or taking care of a common concern, do so. It’s our job to contain chaos so that it’s easier and faster to build excellent software products. | -| **Built to spec** | Every interaction spec’d should be implemented. The [design spec](/component-checklist/#design-spec) should match the implementation perfectly down to the pixel. | Thorough implementation with intense attention to detail is pivotal to maintaining pervasive design excellence within the system. This high bar of quality is what sets our system apart and drives adoption, user satisfaction, and overall outcomes. | -| **Tokens** | Component styles use tokens available in the system Component styles do not contain magic numbers or colors that are not tokenized | Tokens are essential to the reusability and scalability of the system - they support a11y requirements and reduce the maintenance burden within the system. | -| **Globalization** | All strings are configurable and parameterized (props) in a way that is agnostic and compatible with a wide range of g11n i18n solutions/libraries | Ensures assets can be reused within products and offerings worldwide. | -| **Responsiveness** | Component layout, functionality, and ux works on all device sizes from very large to ~320px wide Component styles use media queries where needed | Ensures assets work properly on small screens so that IBM products and offerings can be used on as many devices as possible. | +| **API guiding principles** | Prioritize end user: put the consumer/dev experience above how difficult it might be for us to implement. Interoperability: support wide band coverage of multiple react versions, node LTS versions, etc. and prefer framework/library agnostic approaches to component APIs and designs.Stability: always deprecate before removal, ensure long deprecation periods, consider the migration experience for developers. Composition: components should be broken down into logical pieces to support the many disparate configurations that are required by the business. Developer Experience: consider how a developer will use this component; will they find it approachable, confusing, complex, too simple? | Careful consideration of API design ensures that future changes to the system can be made in an iterative way that minimize disruption. Developer experience and productivity can be heavily influenced by confusing or needlessly complex APIs. The business has a wide range of requirements and should meet as many of them as possible. Prioritize the user wherever possible - if we can make things easier for them by writing extra code, handling complexity internally, or taking care of a common concern, do so. It’s our job to contain chaos so that it’s easier and faster to build excellent software products. | +| **Built to spec** | Every interaction spec’d should be implemented. The [design spec](/contributing/component-checklist/#design-spec) should match the implementation perfectly down to the pixel. | Thorough implementation with intense attention to detail is pivotal to maintaining pervasive design excellence within the system. This high bar of quality is what sets our system apart and drives adoption, user satisfaction, and overall outcomes. | +| **Tokens** | Component styles use tokens available in the system. Component styles do not contain magic numbers or colors that are not tokenized. | Tokens are essential to the reusability and scalability of the system - they support a11y requirements and reduce the maintenance burden within the system. | +| **Globalization** | All strings are configurable and parameterized (props) in a way that is agnostic and compatible with a wide range of g11n i18n solutions/libraries. | Ensures assets can be reused within products and offerings worldwide. | +| **Responsiveness** | Component layout, functionality, and ux works on all device sizes from very large to ~320px wide. Component styles use media queries where needed. | Ensures assets work properly on small screens so that IBM products and offerings can be used on as many devices as possible. | | **Storybook** | A default and playground story exists in Storybook. | Ensures re-usable code and a demo are available. | -| **Documentation** | Long-form documentation is provided in both storybook and the carbon website | Usage examples in storybook do not answer all questions, cover all interactions, or provide pointed helpful information regarding the intended component usage and configuration. | -| **Fully Typed/JSDoc** | Component has an interface with all props typed Component interface is exported for use in consuming projects | Ensures that components and assets are built using Typescript to attain the inherent benefits of strongly typed programming language, but also provides a best in class developer experience (particularly through intellisense), even for those not using TypeScript in their projects. | -| **Codemods** | If the component/change will require migration by consuming teams, an automated code migration script should be written and made available through `@carbon/upgrade` | Ensure that consumers using a given component will have a graceful experience when breaking changes occur. Also holds a lot of weight as to the perception of the system’s ability to adapt and innovate while maintaining a laser-focus on stability. Reduces the cost spent by a team to migrate - compounded across all the teams we support across IBM this can have a significant impact on IBM’s bottom line in cost/productivity. | +| **Documentation** | Long-form documentation is provided in both storybook and the carbon website. | Usage examples in storybook do not answer all questions, cover all interactions, or provide pointed helpful information regarding the intended component usage and configuration. | +| **Fully Typed/JSDoc** | Component has an interface with all props typed. Component interface is exported for use in consuming projects. | Ensures that components and assets are built using Typescript to attain the inherent benefits of strongly typed programming language, but also provides a best in class developer experience (particularly through intellisense), even for those not using TypeScript in their projects. | +| **Codemods** | If the component/change will require migration by consuming teams, an automated code migration script should be written and made available through `@carbon/upgrade`. | Ensure that consumers using a given component will have a graceful experience when breaking changes occur. Also holds a lot of weight as to the perception of the system’s ability to adapt and innovate while maintaining a laser-focus on stability. Reduces the cost spent by a team to migrate - compounded across all the teams we support across IBM this can have a significant impact on IBM’s bottom line in cost/productivity. | @@ -106,9 +106,9 @@ be considered stable. | Requirement | Details | Why this matters | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Unit testing** | Component API and functionality should be thoroughly tested using jest and testing-library (therefore in a jsdom environment) Component unit test coverage should meet and exceed 80% of functions, lines, statements, etc. | Validates and ensures that components work as they’re expected to and regressions are not introduced as changes are made. | -| **Visual regression tests (VRT)** | Component has at least one test for VRT using Percy - the default story Additional “problematic” or highly concerning component states, stories, viewport-widths can be covered by VRT | Ensures that components do not visually regress as changes are made. This catches bugs early, avoids disruptive mistakes, and supports the overall stability of the system. | -| **Accessibility verification tests (AVT)** | Component has one test of it’s default state checked by [accessibility-checker](https://www.ibm.com/able/toolkit/verify/automated) Component has all additional “complex” states (open, closed, highlighted, expanded, focused, hovered, clicked, etc) checked by accessibility-checker | Ensures that components and assets are accessible. First and foremost this is a moral imperative; accessibility benefits everyone. It additionally supports the goal of IBM products and offerings being able to be sold and used in industries bound by law to have accessible experiences. | +| **Unit testing** | Component API and functionality should be thoroughly tested using jest and testing-library (therefore in a jsdom environment). Component unit test coverage should meet and exceed 80% of functions, lines, statements, etc. | Validates and ensures that components work as they’re expected to and regressions are not introduced as changes are made. | +| **Visual regression tests (VRT)** | Component has at least one test on the default story for VRT using Percy. Additional “problematic” or highly concerning component states, stories, viewport-widths can be covered by VRT. | Ensures that components do not visually regress as changes are made. This catches bugs early, avoids disruptive mistakes, and supports the overall stability of the system. | +| **Accessibility verification tests (AVT)** | Component has one test of it’s default state checked by the [IBM Equal Access Accessibility Checker](https://www.ibm.com/able/toolkit/tools/#develop). Component has all additional “complex” states (open, closed, highlighted, expanded, focused, hovered, clicked, etc) checked by IBM Equal Access Accessibility Checker. | Ensures that components and assets are accessible. First and foremost this is a moral imperative; accessibility benefits everyone. It additionally supports the goal of IBM products and offerings being able to be sold and used in industries bound by law to have accessible experiences. | | **Screen reader/voiceover** | Component has been manually tested to read appropriately in JAWS, VoiceOver, and NVDA. | Ensures that components and assets are able to be used by disabled users who utilize screenreaders. First and foremost this is a moral imperative; accessibility benefits everyone. It additionally supports the goal of IBM products and offerings being able to be sold and used in industries bound by law to have accessible experiences. | @@ -150,8 +150,8 @@ governance model. | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **IBM Figma guidelines** | Figma components follow the guidelines as defined in [IBM Figma Best Practices](https://www.figma.com/design/4UYvy6eey28bD3IvtNF8xP/IBM-Documentation-Library?node-id=654-4435&t=67lxOP8nwgq7z2E1-0).

The guidance includes topics on component properties, auto layout, styles, icons, item and base components, content, construction, and file organization. | This checklist ensures components are built correctly before being merged into the main Figma branch. | | **IBM Figma Naming Convention** | Figma components follow the component naming convention documented in [IBM Figma Best Practices](https://www.figma.com/design/4UYvy6eey28bD3IvtNF8xP/IBM%C2%AE-Documentation-Library?m=auto&node-id=642-4479&t=1rSjk0nlj8wBV9aK-1). | The naming convention ensures that file architecture and component hierarchies are both standardized and intuitive for the user.

With this method we are able to have hierarchy between the final components, their bases, and their pieces when we traverse through the assets/instance swapper panels while still being able to view the entire component name when doing a search. | -| **Built to spec** | The Figma component should match the [design spec](/component-checklist/#design-spec) perfectly down to the pixel. Every interaction spec’d should be included in the Figma component. | Thorough implementation with intense attention to detail is pivotal to maintaining pervasive design excellence within the system. This high bar of quality is what sets our system apart and drives adoption, user satisfaction, and overall outcomes. | -| **Published to a library** | A Figma component must be published to the appropriate IBM Figma library. Components built in the Carbon repo are published in [(V11) All themes - Carbon Design System](). | A published connected component ensures accurate use across products. It also allows for Figma analytic tracking. | +| **Built to spec** | The Figma component should match the [design spec](/contributing/component-checklist/#design-spec) perfectly down to the pixel. Every interaction spec’d should be included in the Figma component. | Thorough implementation with intense attention to detail is pivotal to maintaining pervasive design excellence within the system. This high bar of quality is what sets our system apart and drives adoption, user satisfaction, and overall outcomes. | +| **Published to a library** | A Figma component must be published to the appropriate IBM Figma library. Components built in the Carbon repo are published in [(V11) All themes - Carbon Design System](). | A published connected component ensures accurate use across products. It also allows for Figma analytic trackingto better understand adoption and usage. |