diff --git a/src/data/nav-items.yaml b/src/data/nav-items.yaml
index 477a17e74b0..a19dd7badef 100644
--- a/src/data/nav-items.yaml
+++ b/src/data/nav-items.yaml
@@ -42,11 +42,9 @@
- title: Contributing
pages:
- title: Get started
- path: /contributing/get-started/
- - title: Code
- path: /contributing/code/
- - title: Design
- path: /contributing/design/
+ path: /contributing/get-started/overview
+ - title: Component checklist
+ path: /contributing/component-checklist/
- title: Documentation
path: /contributing/documentation/
- title: Migrating
diff --git a/src/pages/contributing/component-checklist/index.mdx b/src/pages/contributing/component-checklist/index.mdx
new file mode 100644
index 00000000000..a1e24f037a9
--- /dev/null
+++ b/src/pages/contributing/component-checklist/index.mdx
@@ -0,0 +1,159 @@
+---
+title: Component checklist
+description:
+ When building components in the Carbon ecosystem, it’s essential that we align
+ on a “definition of done” to ensure all components are being built with the
+ same quality and assurance.
+---
+
+import { UnorderedList, ListItem } from '@carbon/react';
+
+
+
+When building components in the Carbon ecosystem, it’s essential that we align
+on a “definition of done” to ensure all components are being built with the same
+quality and assurance.
+
+
+
+
+
+Definition of done
+Design spec
+Code
+Documentation
+Design kit
+
+
+
+## Definition of done
+
+By aligning on the requirements of component stability, we can easily prioritize
+a backlog of work, share the status of assets with contributors and better
+differentiate when an asset is a component versus a pattern. We can also work
+backward from this strict list of requirements to inform where a component
+currently is in the
+[Product Development Lifecycle](https://w3.ibm.com/w3publisher/winning-products/how-we-work/product-development-lifecycle)
+(PDLC). With each phase, the component should progress in its completeness. Once
+it has reached stable and all items in the following checklists have been
+completed, then the component will be considered done.
+
+Note: Although not all published assets currently meet these requirements,
+moving forward, we’d like all new assets to adhere to them.
+
+| Status | PDLC Phase | Description |
+| ------------------- | ---------------- | ------------------------------------------------------------------------------------ |
+| `Draft` | Discovery | Partially complete, ready for validation. |
+| `Preview candidate` | Discovery | Partially complete, with measurable results, stakeholders, and clear business value. |
+| `Preview` | Delivery | Mostly complete, changes possible based on feedback, available to use in production. |
+| `Stable` | Launch and scale | Complete across code, kit, docs, design, and ready for production use. |
+
+## Design spec
+
+The design specification (spec) is the blueprint used by developers to build the
+component in code and for designers making the component in Figma. It is
+referenced as the source of truth for the visual appearance and functionality of
+a component. Having an accurate and detailed design spec ensures the component
+will be built and represented consistently across experiences.
+
+
+
+
+| Requirement | Details | Why this matters |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Color tokens** | Design specs only use color tokens available in the system.Design specs only contain colors that are tokenized.Color token usage is correct according to our documentation and matches applications across the system. | Color tokens are essential to the reusability and scalability of the system; they support a11y requirements and reduce the maintenance burden. They also allow for consistent application of color across the system, and make color functionalities like theming possible. |
+| **Type tokens** | Design specs only use type tokens available in the system.Design specs only contain type styles and sizes that are tokenized.Type token usage is correct and consistent with matching applications across the system. | Type tokens are essential to the reusability and scalability of the system and they reduce the maintenance burden. They also allow for consistent type use across the system. |
+| **Structure and measurements** | Design specs only use spacing tokens available in the system.Clearly annotate spacing and alignment for all design elements.Design specs include all possible configurations such as sizes and content configurations. | Detailed structure and measurement specs allow developers to build assets quicker and ensure that designs are accurately represented in the code. |
+| **Interaction states** | Designs include specs for states such as hover, focus, selected, disabled, read-only, error, warning, etc. | Each state of the component needs to be represented in the specification to ensure that accessibility requirements and quality of the designs are accurately represented in the code. |
+| **Behaviors** | Designs include specs for behaviors such as responsiveness, content overflow or reflow, expansion, scrolling, etc. | Developers need to understand how the asset will behave when a user interacts with it. Detailed annotations and specs of the various behaviors will ensure that the designs are accurately represented in the code. |
+| **Accessibility** | All text colors pass 4.5:1 color contrast with the exceptions of disabled states.All interactive non-text elements meet 3:1 contrast.Flow of focus is clearly documented. | IBM products must meet WCAG AA accessibility standards. |
+
+
+
+
+## Code
+
+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: emphasize the consumer/dev experience above difficulty of implementation. Interoperability: support wide band coverage of multiple React versions, node LTS versions, etc. and favor 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 or confusing? | Careful consideration of API design ensures that future changes to the system can be made in an iterative way that minimizes disruption. Developer experience and productivity can be heavily influenced by 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 you 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 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 the 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. |
+
+
+
+
+### Testing
+
+A crucial aspect to ensure continued quality of production stable code is
+testing. The following testing requirements must be met before a component can
+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 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. |
+
+
+
+
+## Documentation
+
+All components and patterns require usage, style, code, and accessibility
+guidance published on a Carbon ecosystem website. Carbon provides documentation
+templates to help ensure visual and content expectations. Additional guidance on
+creating layouts and images for website documentation can be found in the
+[image production guidelines](https://carbondesignsystem.com/designing/design-resources/#image-production-guidelines).
+
+
+
+
+| Requirement | Details | Why this matters |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **xxUsage docs** | [Single variant template](/contributing/documentation/#usage-template:-for-components-with-one-variant) _(last updated Q1 2024)_. [Multiple variant template](/contributing/documentation/#usage-template:-for-components-with-multiple-variants) _(last updated 2021)_. | The usage documentation helps describe when to use a component and how it works. |
+| **Style docs** | [Single variant template](/contributing/documentation/#style-template:-for-components-with-one-variant) _(last updated Q3 2024)_. [Multiple variant template](/contributing/documentation/#style-template:-for-components-with-multiple-variants) _(last updated Q3 2024)_. | The style documentation helps describe how a component looks, including visual specifications such as color, typography, structure, and size. |
+| **Code docs** | [Code template](/contributing/documentation/#code-template) _(last updated 2022)_. | The code documentation helps developers implement the component. It includes code snippets, dependencies, and version changes. Although Carbon developers write more detailed documentation in Storybook, they still provide several standard pieces of information on the Carbon website. |
+| **Accessibility docs** | [Accessibility template](/contributing/documentation/#accessibility-template) _(last updated 2023)_. | The published information, written by our A11y SMEs, helps users understand all the accessibility considerations that are baked into Carbon. |
+
+
+
+
+## Design kit
+
+Our
+[IBM Figma best practices](https://www.figma.com/design/4UYvy6eey28bD3IvtNF8xP/IBM-Documentation-Library?node-id=654-4435&t=67lxOP8nwgq7z2E1-0)
+are maintained, tracked, and peer-reviewed by IBM’s Figma guild. Although the
+guild is not part of the Carbon team, they are crucial partners in our
+governance model.
+
+
+
+
+| Requirement | Details | Why this matters |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **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 merging 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 searching. |
+| **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 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) Carbon Design System](). | A published connected component ensures accurate use across products. It also allows for Figma analytics to understand adoption and usage better. |
+
+
+
diff --git a/src/pages/contributing/code.mdx b/src/pages/contributing/get-started/code.mdx
similarity index 98%
rename from src/pages/contributing/code.mdx
rename to src/pages/contributing/get-started/code.mdx
index 1dc5365732a..6cc5a76a922 100644
--- a/src/pages/contributing/code.mdx
+++ b/src/pages/contributing/get-started/code.mdx
@@ -1,8 +1,9 @@
---
-title: Code
+title: Getting started
description:
Code contributions can include anything from squashing bugs to adding feature
requests. Check out the instructions below to contribute code effectively.
+tabs: ['Overview', 'Code', 'Design']
---
export const Title = () => Contribute code;
diff --git a/src/pages/contributing/design.mdx b/src/pages/contributing/get-started/design.mdx
similarity index 98%
rename from src/pages/contributing/design.mdx
rename to src/pages/contributing/get-started/design.mdx
index ecc4a3499ff..bbc5a0f29c1 100644
--- a/src/pages/contributing/design.mdx
+++ b/src/pages/contributing/get-started/design.mdx
@@ -1,9 +1,10 @@
---
-title: Design
+title: Getting started
description:
Design contributions can involve anything from creating design specs for
feature requests to maintaining Figma libraries. Below you'll find tips and
best practices to get started.
+tabs: ['Overview', 'Code', 'Design']
---
export const Title = () => Contribute design;
diff --git a/src/pages/contributing/images/carbon-tutorial.gif b/src/pages/contributing/get-started/images/carbon-tutorial.gif
similarity index 100%
rename from src/pages/contributing/images/carbon-tutorial.gif
rename to src/pages/contributing/get-started/images/carbon-tutorial.gif
diff --git a/src/pages/contributing/images/combo-button.gif b/src/pages/contributing/get-started/images/combo-button.gif
similarity index 100%
rename from src/pages/contributing/images/combo-button.gif
rename to src/pages/contributing/get-started/images/combo-button.gif
diff --git a/src/pages/contributing/images/icon-only-switcher.gif b/src/pages/contributing/get-started/images/icon-only-switcher.gif
similarity index 100%
rename from src/pages/contributing/images/icon-only-switcher.gif
rename to src/pages/contributing/get-started/images/icon-only-switcher.gif
diff --git a/src/pages/contributing/images/left-hand-nav-delay.gif b/src/pages/contributing/get-started/images/left-hand-nav-delay.gif
similarity index 100%
rename from src/pages/contributing/images/left-hand-nav-delay.gif
rename to src/pages/contributing/get-started/images/left-hand-nav-delay.gif
diff --git a/src/pages/contributing/images/read-only-form-inputs.gif b/src/pages/contributing/get-started/images/read-only-form-inputs.gif
similarity index 100%
rename from src/pages/contributing/images/read-only-form-inputs.gif
rename to src/pages/contributing/get-started/images/read-only-form-inputs.gif
diff --git a/src/pages/contributing/images/two-handle-slider.gif b/src/pages/contributing/get-started/images/two-handle-slider.gif
similarity index 100%
rename from src/pages/contributing/images/two-handle-slider.gif
rename to src/pages/contributing/get-started/images/two-handle-slider.gif
diff --git a/src/pages/contributing/get-started.mdx b/src/pages/contributing/get-started/overview.mdx
similarity index 89%
rename from src/pages/contributing/get-started.mdx
rename to src/pages/contributing/get-started/overview.mdx
index 6cb81f99786..175eb0cd42f 100644
--- a/src/pages/contributing/get-started.mdx
+++ b/src/pages/contributing/get-started/overview.mdx
@@ -1,9 +1,10 @@
---
-title: Get started
+title: Getting started
description:
- The Carbon Design System is made possible through a vibrant community of
- designers and developers. Anyone can contribute code, design, documentation,
- and ideas. Here's how you can contribute, too!
+ Design contributions can involve anything from creating design specs for
+ feature requests to maintaining Figma libraries. Below you'll find tips and
+ best practices to get started.
+tabs: ['Overview', 'Code', 'Design']
---
@@ -192,6 +193,15 @@ solutions and then creating a design spec for developers.
[Here are issues](https://github.com/carbon-design-system/carbon/issues?q=is%3Aopen+is%3Aissue+label%3A%22needs%3A+community+contribution%22+)
in our enhancement backlog that need design or development work.
+### New components
+
+New components are a large multidiscipline contribution and must be contributed
+in phases to insure quality and business value. To propose a net new component,
+follow the [phased contribution process](/contributing/contribution-process) and
+complete all requirements in the
+[component checklist](contributing/component-checklist). All requirement
+categories must be completed before a component can be considered done.
+
### Design kits
This work is all about creating and updating reusable components in Figma.
@@ -226,8 +236,14 @@ on the IBM Design Language site.
## The process
-Whether you're contributing code, designs, or documentation, there's a process
-to follow. Here's what it looks like:
+Whether you’re contributing code, designs, or documentation, there’s a process
+to follow. For larger contributions like new components or patterns a more
+rigorous process must be followed to insure production level quality and
+business value. We have laid out the phases and criteria on the next page in
+[contribution process](contributing/contribution-process).
+
+For smaller contributions like small additions, enhancements, or bug fixes
+follow the process below.
### 1. Find a project to work on
@@ -262,7 +278,7 @@ Guild, Data Viz Guild, or office hours. In these sessions, it is common to share
work in progress and ask lots of questions. As you make progress, update your
GitHub issue.
-### 3. Review and publish
+### 3. Submit for review
#### Code deliverables
diff --git a/src/styles/_component-checklist.scss b/src/styles/_component-checklist.scss
new file mode 100644
index 00000000000..8e95570a511
--- /dev/null
+++ b/src/styles/_component-checklist.scss
@@ -0,0 +1,16 @@
+//---------------------------------------
+// Contributing / Component checklist
+//---------------------------------------
+
+// custom table styles
+// align to grid
+.table--component-checklist .page-table {
+ th:first-child {
+ // 2 columns
+ width: 15.4%;
+ }
+ th:nth-child(2) {
+ // 5 columns
+ width: 43%;
+ }
+}
diff --git a/src/styles/index.scss b/src/styles/index.scss
index 3ce37c81b85..66abbf73c53 100644
--- a/src/styles/index.scss
+++ b/src/styles/index.scss
@@ -8,6 +8,7 @@
@import 'structured-list';
@import 'plex-serif';
@import 'meetups';
+@import 'component-checklist';
@import 'overrides';
@import 'src/components/ColorBlock/color-block.scss';
@import 'src/components/ColorGrid/color-grid.scss';