Context
Our design system currently has only one component package, the Component Library Package. We also have a number of Octopus-server-specific components that live in the application itself. These components are often reused across the product but are very specific Octopus concepts. This can cause duplication, repetition, and inconsistencies, often resulting in orphaned components, making them difficult to maintain and manage. In addition, these Octopus-server-specific components lack documentation as they are not part of the design system.
We propose dividing the Design System packages into two packages: a Component library package containing basic, reusable, universal components and an Octopus-server-specific package containing custom components tailored to the Octopus product's specific and unique needs and design requirements.
Problem
A lack of documentation and incorrectly categorising components can lead to confusion, redundant development efforts, and inconsistencies in the user experience. Clear guidelines for determining whether a component should reside in generic or company-specific packages are essential.
Guidelines for Component Placement
Whether a component should exist in the component library package or the Octopus-specific package should be decided during component discovery.
- Generic Package:
- Universal Use: Components that provide basic, widely applicable functionality and can be used across multiple projects. Examples include buttons, input fields, dialogs, and layout components.
- Standard Design Patterns: Components that adhere to industry-standard design patterns and are not tailored to any specific custom Octopus functionality
- Reusability: Components intended to be reused in various contexts without requiring significant customization for each use case.
- Octopus-server-specific Package:
- Custom Functionality: Components that implement features or behavior specific to our products, user base, or business needs. This includes needing access to Octopus-server-specific packages/modules that we want to keep out of the generic package.
- Specialized Use Cases: Complex components designed for particular workflows that are unique to a team concept or area.
- Reusability: Components intended to be reused in various contexts without requiring significant customization for each use case.
Key Considerations
- Maintainability: Ensure components are placed in the correct package to avoid duplication and streamline updates and maintenance.
- Scalability: When determining their placement, consider the potential for components to be adapted for broader use.
- Consistency: Use design tokens shared between both packages to maintain a cohesive look and feel across all components, regardless of their placement.
Ongoing maintenance
As the design system evolves, we will review and adjust component placements to ensure that they align with our needs and that the generic and octopus-specific packages remain well-organised and clear.
The Solution
-
Code Component Library: A new package will be created for the Octopus-server-specific components; the decision process for determining how these components are categorised is outlined above under Guidelines for Component Placement.
Our design system will be organised into two main parts: generic concepts and Octopus-specific concepts. - Generic concepts: These are basic reusable elements. They provide standard functionality and styling that works universally. Generic components are managed in a central package with related documentation for easy use.
- Octopus-specific concepts: These are custom reusable elements tailored to our company’s specific needs. They build on the generic components with features specific to our product. Octopus-specific components are kept in a separate package. Documentation and Figma components will exist in the same place as the generic concepts but will indicate that they are stored in the Octopus-specific package.
- Figma Component library: The Figma component library will remain the same; however, the component will indicate that it belongs to the Octopus-server-specific component
- Component Library Documentation: Octopus-server-specific components will be included in the list of components along with the components in our generic component library package. The documentation will indicate that it belongs to the Octopus-server-specific package, and import statements will reflect the different import paths.
Both types of components share common design tokens, such as color and spacing, to ensure consistency in visual design.
This structure helps us maintain consistency with generic components while allowing customisation through Octopus-specific elements.