Skip to main content

ODS to Abyss Token Conversion Strategy

  • Status: Deprecated
  • Deciders: Stakeholders
  • Date: 06/03/2025
  • Deprecated Date: 12/18/2025
  • Deprecated Reason: Strategic direction change - ODS integration approach superseded by alternative solutions

Deprecation Notice​

This ADR has been deprecated as of December 18, 2025.

The strategic approach outlined in this document for ODS to Abyss token conversion has been superseded by alternative integration solutions. The complexity and maintenance overhead identified in the consequences section led to the adoption of a different architectural approach.

Context​

The Abyss component library is built using a specific token system structure and needs to support ODS design standard values. We need to map and convert ODS design values to Abyss tokens so that Abyss components can consume them, which presents several structural and maintenance challenges.

Abyss uses a three-tier token structure (core/semantic/component) organized in a deep hierarchical model, while ODS provides a design standard with a taxonomy for referencing specific style values. This architectural difference creates challenges when attempting to make Abyss components compatible with ODS.

Decision​

We will create a dedicated conversion system that performs direct value mapping at runtime with these key components:

  1. A value mapping definition layer that explicitly maps ODS design standard references to their Abyss component token equivalents
  2. A value transformation layer that handles structural differences (like compound values) while preserving ODS's design values
  3. A maintenance strategy including documentation and update procedures for both systems
  4. A dedicated repository location for these mapping files to facilitate maintainability

Alternative Considered​

ODS Adopting Abyss Token Structure​

Advantages:

  • Would eliminate the need for conversion utilities and their associated maintenance overhead
  • Removes the risk of mapping errors or inconsistencies between ODS and Abyss
  • ODS could still own their design decisions while benefiting from seamless integration with Abyss components
  • Greater reliability: Components would be guaranteed to receive all required token values in their expected format
  • Leverages Abyss's established testing infrastructure to ensure tokens are applied correctly
  • Provides a more sustainable long-term solution as both systems evolve

Disadvantages:

  • Represents a significant change to ODS's established design standard and workflow
  • Requires upfront investment to transform ODS design values into Abyss's token structure
  • Requires ODS team to learn and adopt new tools like Figma Token Studio and Abyss's token generation process
  • Reduces ODS's autonomy in maintaining their design standard independently
  • Creates a dependency on Abyss's token structure for future design standard updates

Consequences​

Positive​

  • Design System Independence: Enables ODS to use Abyss components while maintaining their existing token architecture
  • Design Intent Preservation: Allows ODS to preserve their design language and values without compromise
  • Minimal Disruption: Avoids the need for ODS to restructure their entire token system or retrain their team
  • Extensibility: Provides a structured approach that could be extended to other design systems beyond ODS
  • Incremental Adoption: Permits gradual adoption of Abyss components without wholesale migration
  • Separation of Concerns: Maintains clear boundaries between design systems, allowing each to evolve independently

Negative​

  • Development Overhead: Requires significant effort to develop and maintain the mapping and conversion utilities
  • Ongoing Maintenance: Creates a new artifact (mapping files) that must be maintained as both systems evolve
  • Complexity: Introduces additional complexity in the build and runtime processes for ODS applications
  • Mapping Challenges: Some token concepts may not have direct equivalents, requiring complex transformations
  • Testing Burden: Necessitates comprehensive testing to ensure visual consistency across different environments
  • Versioning Complexity: Requires careful versioning to handle updates to either token system
  • Potential for Inconsistencies: Creates risk of visual or behavioral inconsistencies if mappings are incomplete or incorrect

Future Considerations​

  • Align ODS more closely with Abyss's token structure
  • Establishment of automated testing to validate token conversion correctness
  • Evaluate extending this approach to other design systems beyond ODS

Analysis of Token System Differences​

Note: This analysis is primarily based on the button component, as these are the only component values currently available from ODS. Additional patterns may emerge as more ODS component value sets are analyzed.

1. Fundamental Structural Differences​

AspectAbyss ApproachODS Approach
Token HierarchyThree-tiered: core → semantic → componentPrimarily component-focused with limited abstraction
Value ReferencesUses semantic token referencesUses direct values in most cases
State HandlingConsistent state names (rest, hover, active)Mix of state patterns (default, hover, active)
Variant HandlingCombined variant-color system (filled-brand, outline-destructive)Separates themes, variants, and colors (themes.light.primary)

Examples:

  • Abyss: button.color.surface.container.filled-brand.rest references {web.semantic.color.surface.interactive.standards.rest.default.primary}
  • ODS:
{
  "component": "button",
  "brand": "optum",
  "group": "themes",
  "category": "light",
  "subcategory": "",
  "variant": "primary",
  "state": "default",
  "section": "container",
  "property": "background-color",
  "value": "{ds.btnColors.themes.light.primary.default.background.color.value}"
}

2. Key Mapping Challenges​

Detailed analysis of the Button component reveals challenges requiring manual intervention:

  1. Compound vs. Split Values: ODS uses CSS shorthand values that must be split in Abyss

    • ODS: {"property": "padding", "value": "7px 16px"}
    • Abyss: Separate tokens for button.spacing.padding.horizontal and button.spacing.padding.vertical

  2. State Representation Differences: ODS uses explicit state field values ("default", "hover", "active", "disabled") where Abyss uses path segments ("rest" instead of "default")

  3. Property and Section Organization: Different terminology and structure for the same concepts

    • ODS: {"section": "label", "property": "font-color"}
    • Abyss path: text.label

  4. Icon Property Organization: ODS uses specific section types ("icon-leading", "icon-trailing") while Abyss groups them

    • ODS separates by position and property: {"section": "icon-leading", "property": "margin-right"}
    • Abyss uses unified tokens: button.sizing.all.icon

  5. Size Mapping Complexity: Size values appear in different locations

    • ODS: In the subcategory field for size values
    • Abyss: As path segments ("sm", "md", "lg")

  6. Variant and Structure Mismatches: Each system has structures without direct equivalents

    • ODS has explicit variant field with values like "primary", "secondary" while Abyss combines variants with colors (e.g., filled-brand, outline-destructive)
    • ODS implements focus with explicit component values while Abyss uses utility functions
    • ODS references global references (e.g., {ds.btnColors...}) while Abyss uses semantic token references

For detailed examples of these challenges, see Button Token Mapping Challenges and Token Structure Analysis.

Component Format Structure​

ODS uses a structured field-based format (referred to as "CTI format" in filenames) with explicit fields for various attributes:

{
  "system": "ds",
  "component": "button",
  "brand": "optum",
  "group": "themes",
  "category": "light",
  "subcategory": "",
  "variant": "primary",
  "state": "default",
  "section": "container",
  "property": "background-color",
  "value": "{ds.btnColors.themes.light.primary.default.background.color.value}",
  "type": "Button"
}

This structured format, with dedicated fields for variant and state, will inform our mapping approach. For configuration purposes, we would define the token structure as:

"tokenStructure": {
  "format": "structured",
  "fields": ["system", "component", "brand", "group", "category", "subcategory", "variant", "state", "section", "property"],
  "valueProperty": "value"
}

Proposed Implementation Strategy​

The following represents a potential approach to implementing the token conversion system. The final implementation may evolve based on further research and development.

1. Potential Mapping Structure​

Token mapping files could be structured as follows to support the various mapping scenarios identified earlier:

// Example token mapping definition - for illustration purposes
{
  // Pattern based mappings for consistent patterns
  "patterns": [
    {
      "odsTokenQuery": {
        "component": "button",
        "group": "themes",
        "category": "light",
        "variant": "primary",
        "state": "default", // "default" state maps to "rest" in Abyss
        "section": "container",
        "property": "background-color"
      },
      "abyssPattern": "button.color.surface.container.filled-brand.rest"
    }
  ],


  // Direct mappings for specific cases using structured queries
  "direct": {
    "odsTokenQuery": {
      "component": "button",
      "group": "structure",
      "section": "container",
      "property": "border-radius"
    },
    "abyssToken": "button.border-radius.all.container"
  },


  // Structural transformations for handling different token structures
  "transformations": {
    // Handle compound values that need to be split (e.g., padding values)
    "compound": {
      "type": "splitPadding",
      "sourceQuery": {
        "component": "button",
        "group": "options",
        "category": "size",
        "subcategory": "small",
        "section": "container",
        "property": "padding"
      },
      "targets": {
        "horizontal": "button.spacing.padding.horizontal.container.sm",
        "vertical": "button.spacing.padding.vertical.container.sm"
      }
    },


    // Handle icon properties that need to be consolidated
    "iconProperties": {
      "type": "consolidateProperties",
      "sourceQueries": [
        {
          "component": "button",
          "section": "icon-leading",
          "property": "min-height"
        },
        {
          "component": "button",
          "section": "icon-leading",
          "property": "min-width"
        },
        {
          "component": "button",
          "section": "icon-leading",
          "property": "margin-right"
        }
      ],
      "target": "button.sizing.all.icon"
    },


    // Handle variant-color combinations
    "variantColorMapping": {
      "type": "combineVariantColor",
      "variants": {
        "primary": "filled-brand",
        "secondary": "outline-brand",
        "tertiary": "text-brand",
        "ghost": "text-brand",
        "destructive": "filled-destructive"
      },
      "sourceQuery": {
        "component": "button",
        "group": "themes",
        "category": "light",
        "variant": "*" // wildcard for any variant value
      },
      "targetPattern": "button.color.*.*.{mapped-variant}"
    },


    // Handle state name differences
    "stateMapping": {
      "type": "mapState",
      "sourceField": "state",
      "mapping": {
        "default": "rest", // "default" state maps to "rest" in Abyss
        "hover": "hover",
        "active": "active",
        "disabled": "disabled"
      }
    },


    // Handle size name mapping
    "sizeMapping": {
      "type": "mapSize",
      "sourceField": "subcategory",
      "sourceQuery": {
        "component": "button",
        "group": "options",
        "category": "size"
      },
      "mapping": {
        "small": "sm",
        "medium": "md",
        "large": "lg"
      }
    }
  }
}

2. Potential Mapping Generation Approach​

A utility could be developed to assist in generating the mapping files. Such a utility might:

  1. Load and analyze both ODS design values and Abyss tokens
  2. Identify potential patterns and correlations between both structures
  3. Generate initial mapping suggestions based on naming conventions and structural similarities
  4. Flag edge cases that would likely require manual review

This would likely be a hybrid approach combining:

  • Automated processes for identifying patterns and generating initial mappings
  • Manual review and refinement for handling edge cases and validating the generated mappings

3. Conceptual Runtime Conversion Process​

At runtime, a conversion utility could:

  1. Load the pre-generated mapping files
  2. Apply the mappings to convert ODS design values to their Abyss token equivalents
  3. Handle transformations like compound value splitting or state name mapping

The specialized transformers (defined during the mapping process) would handle complex cases like those identified in the token analysis section.

4. Potential Development and Deployment Approach​

A separation between development-time mapping generation and runtime token conversion could provide several benefits:

Development-Time Mapping Generation​

A mapping generation utility could serve as a development-time tool:

  1. Mapping Generation Utility:
    • A tool for creating and maintaining mapping files
    • Used during development, not in production
    • Could support a plugin architecture for different design systems

Runtime Token Conversion​

The runtime components could be structured as:

  1. Token Conversion Utility:

    • A lightweight runtime library for applying the mappings
    • Could be included in the Abyss library or as a separate package

  2. ODS-Specific Mappings:

    • Pre-generated mapping files maintained by the ODS team
    • Generated during development and included in builds

Potential Benefits of This Approach​

This separation could provide:

  • Clear ownership boundaries between generic utilities and system-specific mappings
  • Optimized runtime performance by using pre-generated mapping files
  • Flexibility for ODS to update their mappings independently
  • A pattern that could potentially be extended to other design systems

Conceptual Repository Structure​

# Potential structure in Abyss repository
@abyss/mapping-generator/              # Development-time utility
├── core/
│   ├── patterns.js
│   ├── transformers.js
│   └── generator.js
├── interfaces/
│   └── adapter.js
├── reference-adapters/
│   └── ods/
└── cli.js


@abyss/token-converter/                # Runtime utility
├── core/
│   ├── converter.js
│   └── utils.js
├── standard-transformers/
│   ├── splitPadding.js
│   └── stateMapping.js
└── index.js


# Potential structure in ODS repository
@ods/abyss-adapter/                    # ODS adapter for mapping generation
├── adapter.js
├── config.json
└── transformers/


@ods/abyss-mappings/                   # Pre-generated mapping files
├── mappings/
│   ├── button.json
│   ├── input.json
│   └── ...
└── index.js

5. Maintenance Strategy​

The mapping files will need to be updated when:

  • New components are added to either system
  • Token naming conventions change in either system
  • Design values change significantly in either system

6. Known Limitations and Challenges​

Utility-Based Styling​

Abyss web uses utility functions for certain styling aspects, such as focus and typography, that rely on semantic tokens rather than direct component tokens.

For these cases, we would:

  • Document the limitation and provide fallback strategies
  • Where possible, use CSS overrides for critical styling needs

7. Testing Strategy​

  • Unit tests for mapping logic
  • Visual regression tests to catch design inconsistencies
  • Token structure validation to ensure all required Abyss tokens are mapped

References​

Table of Contents