@procore/core-react/dist/ComponentLifecycle.mdx

React library of Procore Design Guidelines

import { Meta } from '@storybook/addon-docs/blocks'
import styled from 'styled-components'
import { colors } from './_styles/colors'

<Meta title="Introduction/Component Lifecycle" />

export const StatusBadge = styled.div`
  display: inline-block;
  padding: 4px 8px;
  border-radius: 4px;
  background-color: ${(props) => props.$background};
  color: ${(props) => props.$color};
  font-weight: 600;
  font-size: 12px !important;
  margin-bottom: 8px;
  text-transform: uppercase;
`

# Component Lifecycle

Understanding the maturity and stability of Core React components.

Each component in Core React is assigned a lifecycle status that indicates its maturity, stability, and recommended usage. These statuses help you make informed decisions about which components to use in your projects.

Component statuses are displayed as badges in the component documentation. Review this page to understand what each status means and how it impacts your implementation.

## Lifecycle Stages

### Stable

<StatusBadge $background={colors.green40} $color={colors.white}>
  Stable
</StatusBadge>

Stable components solve proven use cases and meet all quality standards. These components are production-ready and recommended for general use.

- Fully tested with comprehensive test coverage including unit, integration, and visual regression tests
- Accessible and compliant with WCAG standards
- Complete documentation with usage examples
- Stable API with minimal breaking changes expected in future releases
- Widely used across production applications

### Internal

<StatusBadge $background={colors.magenta50} $color={colors.white}>
  Internal
</StatusBadge>

Internal components are lower-level building blocks for advanced use cases. These components are primarily intended for internal use within the design system.

- Designed for composition and use within other components
- May require deeper understanding of the design system architecture
- Use with caution in application code; prefer higher-level components when available
- API may be more complex or require additional configuration

### Experimental

<StatusBadge $background={colors.orange50} $color={colors.white}>
  Experimental
</StatusBadge>

Experimental components are under active development and may have breaking changes. Use these components with caution and expect changes in future releases.

- API is not finalized and may change based on feedback and testing
- Breaking changes may occur in minor or patch releases
- Documentation may be incomplete or in progress
- Limited production usage; primarily for testing and providing feedback
- May not meet all accessibility or quality standards

### Under Review

<StatusBadge $background={colors.yellow50} $color={colors.gray10}>
  Under Review
</StatusBadge>

Components under review haven't been updated to meet latest standards. These components are functional but may need updates to align with current design system practices.

- Component works but may not follow current design patterns or best practices
- Scheduled for review and potential updates to meet current standards
- Safe to use in production, but improvements are planned
- May have minor inconsistencies with newer components

### Legacy

<StatusBadge $background={colors.gray40} $color={colors.white}>
  Legacy
</StatusBadge>

Legacy components will be phased out but don't have a stable replacement yet. Continue using these components, but be prepared to migrate in the future.

- Component is being phased out in favor of a newer approach
- Still supported and maintained, but no new features will be added
- A replacement component is in development or planning
- Migration path will be provided when replacement is ready
- Safe to use in existing applications, but avoid using in new features

### Deprecated

<StatusBadge $background={colors.red50} $color={colors.white}>
  Deprecated
</StatusBadge>

Deprecated components will be removed in a future release. Do not use these components in new code and plan to migrate existing usage.

- Component is scheduled for removal in a specified future release
- Replacement component or alternative approach is available
- Migration documentation and examples are provided
- Only critical bug fixes will be addressed
- Console warnings may be displayed when using deprecated components

## Making Decisions

When choosing components for your project, consider the following guidelines:

- **For production applications:** Use Stable components whenever possible. Internal and Under Review components are also safe but may require updates in the future.
- **For new features:** Avoid Legacy and Deprecated components. If an Experimental component solves your use case, discuss with the Core team before implementation.
- **For existing code:** Monitor Deprecated and Legacy components and plan migrations. Subscribe to release notes for updates.

## Lifecycle Transitions

Component statuses may change over time as components mature or as the design system evolves:

- **Experimental → Stable:** After testing, feedback incorporation, and meeting quality standards
- **Stable → Under Review:** When design system standards evolve and updates are needed
- **Under Review → Stable:** After updates are completed and reviewed
- **Stable/Internal → Legacy:** When a better approach is identified but replacement isn't ready
- **Legacy → Deprecated:** When a stable replacement is available
- **Deprecated → Removed:** After sufficient migration time and advance notice

All lifecycle transitions are announced in release notes with appropriate migration guidance.