Source: ocean/docs/adr/0003-establishment-of-core-design-tokens-for-web-design.md | ✏️ Edit on GitHub

ADR-0003: Establishment of Core Design Tokens for Web Design (Fonts and Colors)

Date: 2025-07-26

Status

Accepted

1. Context

To ensure strict brand consistency and optimize the design-to-development process for web applications, it is crucial to formally define and manage core design properties. This ADR formally establishes the specific typography and color values, extracted directly from the "Goldfish_Brand_Guidelines.pdf," to serve as the definitive design tokens for our web design system.

2. Decision

The following fonts and colors, as detailed in the "Goldfish_Brand_Guidelines.pdf" and presented as structured JSON tokens below, are formally adopted as the core design tokens for all web design and development. These tokens will be implemented in Figma and serve as the single source of truth for these design attributes.

3. Rationale

Direct Adherence to Brand Guidelines: By directly embedding and utilizing the specified font families, weights, and hex codes from the official brand guidelines, strict adherence to the Goldfish brand identity is guaranteed.
Single Source of Truth: This ADR, coupled with the embedded token data, provides an unambiguous and centralized source of truth for these design properties. This reduces interpretation errors and ensures consistency across design artifacts and developed products.
Foundation for Figma Implementation: The structured token data presented herein is immediately usable for creating and managing design tokens within Figma, enabling a robust, token-based design approach.
Streamlined Design-to-Development Handoff: Clearly defined and agreed-upon values for fonts and colors, in a readily consumable format, will significantly simplify the handoff process. This allows for precise and efficient implementation by developers, minimizing discrepancies between design and code.
Efficiency and Scalability: Future updates to these core design attributes can be managed centrally via these tokens, propagating changes consistently across all instances where they are used.

4. Core Design Tokens (Extracted from "Goldfish_Brand_Guidelines.pdf")

{
  "color": {
    "palette": {
      "white": {
        "value": "#FFFFFF",
        "description": "Primary color for the base of Goldfish's brand."
      },
      "yellow": {
        "value": "#F6F05E",
        "description": "Primary brand color, may be used as full bleed backgrounds or on other elements as needed."
      },
      "orange": {
        "value": "#F85633",
        "description": "Primary brand color, may be used as full bleed backgrounds or on other elements as needed."
      },
      "gray": {
        "800": {
          "value": "#1B1B1B",
          "description": "Part of the grays palette; should be used as either subtle backgrounds or for typography within UI elements."
        },
        "700": {
          "value": "#2E2E2E",
          "description": "Part of the grays palette; should be used as either subtle backgrounds or for typography within UI elements."
        },
        "600": {
          "value": "#585858",
          "description": "Part of the grays palette; should be used as either subtle backgrounds or for typography within UI elements."
        },
        "500": {
          "value": "#7A7978",
          "description": "Part of the grays palette; should be used as either subtle backgrounds or for typography within UI elements."
        },
        "400": {
          "value": "#A3A1A0",
          "description": "Part of the grays palette; should be used as either subtle backgrounds or for typography within UI elements."
        },
        "300": {
          "value": "#BAB8B7",
          "description": "Part of the grays palette; should be used as either subtle backgrounds or for typography within UI elements."
        },
        "200": {
          "value": "#D6D4D2",
          "description": "Part of the grays palette; should be used as either subtle backgrounds or for typography within UI elements."
        },
        "100": {
          "value": "#EDEDEC",
          "description": "Part of the grays palette; should be used as either subtle backgrounds or for typography within UI elements."
        }
      },
      "blue": {
        "value": "#2B50CB"
      },
      "green": {
        "value": "#124B3C"
      },
      "richBlack": {
        "value": "#000000"
      },
      "lightBlue": {
        "value": "#87BDFA"
      },
      "darkBlue": {
        "value": "#0D355E"
      },
      "pink": {
        "value": "#FFCEEB"
      },
      "purple": {
        "value": "#3E2570"
      }
    }
  },
  "font": {
    "family": {
      "headline": {
        "value": "Poly Sans",
        "description": "Primary typeface for headlines."
      },
      "body": {
        "value": "Metro Sans",
        "description": "Primary typeface for body copy and other typographic applications."
      }
    },
    "weight": {
      "polySans": {
        "medium": {
          "value": "Medium",
          "description": "Recommended weight for primary or secondary headlines in Poly Sans."
        }
      },
      "metroSans": {
        "regular": {
          "value": "Regular",
          "description": "Typically used for body copy in Metro Sans."
        },
        "book": {
          "value": "Book",
          "description": "Typically used for body copy in Metro Sans."
        },
        "bold": {
          "value": "Bold",
          "description": "May be used for tertiary headlines or other emphasis in Metro Sans."
        }
      }
    },
    "usage": {
      "headline": {
        "family": "{font.family.headline.value}",
        "weight": "{font.weight.polySans.medium.value}",
        "color": "{color.palette.gray.800.value}",
        "alternativeColor": "{color.palette.richBlack.value}",
        "description": "Primary or secondary headlines. Use black or gray. Color reserved for backgrounds/shapes, not typography."
      },
      "body": {
        "family": "{font.family.body.value}",
        "weight": "{font.weight.metroSans.regular.value}",
        "alternativeWeights": [
          "{font.weight.metroSans.book.value}",
          "{font.weight.metroSans.bold.value}"
        ],
        "color": "{color.palette.gray.800.value}",
        "alternativeColor": "{color.palette.richBlack.value}",
        "description": "All other typographic applications. Regular or book typically used for body copy. All weights may be used depending on situation (e.g., Bold for tertiary headline). Use black or gray. Color reserved for backgrounds/shapes, not typography."
      }
    }
  }
}

5. Consequences

Positive:
- Provides a definitive and immediately actionable reference for all design attributes related to color and typography.
- Enables seamless and precise translation of brand guidelines into Figma and subsequently into code.
- Eliminates ambiguity and ensures consistent visual identity across all web properties.
- Facilitates efficient maintenance and future scaling of the design system.
Negative:
- Requires diligent maintenance of this ADR and the corresponding Figma tokens should the brand guidelines for colors or typography change.

6. Next Steps

Implement these structured design tokens within Figma.

Status​

Status