Overview

This document analyzes the structural patterns between ODS and Abyss token formats, using the button component as a reference implementation. Understanding these patterns is crucial for designing a token conversion strategy.

Token Structure

ODS CTI Example

{
  "category": "light",
  "subcategory": "",
  "variant": "destructive",
  "state": "hover",
  "section": "container",
  "property": "background-color",
  "value": "{ds.btnColors.themes.light.destructive.hover.background.color.value}"
}

Abyss Token Example

{
  "type": "color",
  "category": "surface",
  "element": "container",
  "variant": "filled-destructive",
  "state": "hover",
  "value": "{web.semantic.color.surface.interactive.standards.hover.default.status.error}"
}

Mapping Rules

1. Direct 1:1 Mappings

ODS Property    -> Abyss Property
---------------------------------
state          -> state
value          -> value

2. Property-Based Type Mapping

ODS "property" Value    -> Abyss "type" Property
-------------------------------------------------------
background-color        -> color
border-color            -> color
color-primary           -> color
padding                 -> spacing
min-height              -> sizing
min-width               -> sizing

3. Section Mapping

ODS "section" Value      -> Abyss Property/Value
-------------------------------------------------------
container                -> element: container
label                    -> element: label
icon-leading             -> category: icon
icon-trailing            -> category: icon
icon-only                -> characteristic: icon-only

4. Variant Transformations

ODS "variant" Value      -> Abyss "variant" Value
-----------------------------------------------------
destructive              -> filled-destructive
primary                  -> filled-brand
tertiary                 -> text-brand

5. Category + Property Combinations

ODS "category" + "property" Properties  -> Abyss "category" Property
---------------------------------------------------------------------
light + border-color                    -> border
light + background-color                -> surface
light + color                           -> text
light + color-primary                   -> icon

Example Mappings

Background Color Token

ODS:
{
  "category": "light",
  "property": "background-color",
  "section": "container",
  "variant": "destructive",
  "state": "hover",
  "value": "{ds.btnColors.themes.light.destructive.hover.background.color.value}"
}

Maps to Abyss:
{
  "type": "color",
  "category": "surface",
  "element": "container",
  "variant": "filled-destructive",
  "state": "hover",
  "value": "{web.semantic.color.surface.interactive.standards.hover.default.status.error}"
}

Icon Color Token

ODS:
{
  "category": "light",
  "property": "color-primary",
  "section": "icon-leading",
  "variant": "destructive",
  "state": "hover",
  "value": "{ds.btnColors.themes.light.destructive.hover.icon.color.primary.value}"
}

Maps to Abyss:
{
  "type": "color",
  "category": "icon",
  "variant": "text-destructive",
  "state": "hover",
  "value": "{web.semantic.color.icon.interactive.hover.status.error}"
}

Border Color Token

ODS:
{
  "category": "light",
  "property": "border-color",
  "section": "container",
  "variant": "destructive",
  "state": "hover",
  "value": "{ds.btnColors.themes.light.destructive.hover.border.color.value}"
}

Maps to Abyss:
{
  "type": "color",
  "category": "border",
  "variant": "outline-brand",
  "state": "hover",
  "value": "{web.semantic.color.border.content.primary}"
}