Adding New Protocol Colors

Auto-generate your docs

This guide walks you through the process of adding new protocol colors to the Color Palettes project. Follow these steps carefully to ensure your contribution meets all requirements.

Understanding the Schema

The color palettes are maintained in JSON format with a specific structure:

{
  "protocol_name": {
    "hex": "#color_code",
    "aliases": ["alias1", "alias2"]
  }
}

Schema Properties

string

required

The official name of the protocol or chain. This should match the brand’s official name exactly.Pattern: ^[A-Za-z0-9\\s\\-_().₮]+$Examples: Ethereum, Uniswap, Polygon zkEVM

string

required

The hex color code of the protocol’s primary brand color.Pattern: ^#[0-9A-Fa-f]{6}$Examples: #627EEA, #FF007A, #8247E5

array

required

Common variations of the protocol name used in queries. Must contain at least one alias.Item Pattern: ^[a-zA-Z0-9_\\s.₮-]+$Requirements:

Minimum 1 alias
All aliases must be unique (no duplicates within the array)
Lowercase recommended for consistency

Examples: ["ethereum", "eth", "weth"], ["uniswap", "uni"]

Step-by-Step Process

Research the Protocol

Before adding a new protocol, gather accurate information:

Find Official Brand Colors

Check these sources in order of preference:

Official Brand Kit: Many protocols provide downloadable brand assets
Press/Media Pages: Often include brand guidelines
Official Website: Use browser DevTools to inspect CSS for exact hex values
Official Documentation: May specify brand colors
GitHub Repository: Check for brand asset files

Never guess colors or use colors from unofficial sources. If you can’t find official brand colors, open an issue to discuss with maintainers.

Identify Common Aliases

Consider how the protocol appears in Dune Analytics:

Full protocol name (lowercase)
Official ticker/symbol
Common abbreviations
Chain identifiers used in Dune
Version-specific names (e.g., uniswap_v2, uniswap_v3)

Run sample queries in Dune to see how the protocol name appears in actual data.

Check for Existing Entries

Before proceeding, verify the protocol isn’t already in the collection:

# Search for the protocol name
cat color-palettes.json | jq 'keys[] | select(. | ascii_downcase | contains("protocol_name"))'

# Search for specific aliases
cat color-palettes.json | jq -r 'to_entries[] | select(.value.aliases[] | contains("alias")) | .key'

Prepare Your Entry

Create your protocol entry following the schema:

"Protocol Name": {
  "hex": "#HEXCODE",
  "aliases": ["alias1", "alias2", "alias3"]
}

"Ethereum": {
  "hex": "#88AAF1",
  "aliases": ["ethereum", "eth", "weth"]
}

"Arbitrum": {
  "hex": "#12AAFF",
  "aliases": ["arbitrum", "arbitrum one", "arb"]
}

"Uniswap": {
  "hex": "#F50DB4",
  "aliases": ["uniswap", "uni"]
}

"Polygon zkEVM": {
  "hex": "#A128C5",
  "aliases": ["zkevm"]
}

Checklist before proceeding:

Protocol name matches official branding exactly
Hex code is 6 digits with # prefix
All hex digits are valid (0-9, A-F)
At least one alias provided
All aliases are lowercase
No duplicate aliases within the entry

Edit the Color Palettes File

Add your entry to color-palettes.json:

Open the file in your preferred editor
Find the appropriate location (alphabetical order recommended but not required)
Add your entry with proper JSON formatting
Ensure proper commas between entries

{
  "Arbitrum": {
    "hex": "#12AAFF",
    "aliases": ["arbitrum", "arbitrum one", "arb"]
  },
  "Base": {
    "hex": "#0052FF",
    "aliases": ["base"]
  }
}

{
  "Arbitrum": {
    "hex": "#12AAFF",
    "aliases": ["arbitrum", "arbitrum one", "arb"]
  },
  "Base": {
    "hex": "#0052FF",
    "aliases": ["base"]
  },
  "Optimism": {
    "hex": "#FF0420",
    "aliases": ["optimism", "op mainnet", "op"]
  }
}

Common JSON Mistakes:

Missing comma between entries
Extra comma after last entry
Missing quotes around strings
Incorrect bracket/brace nesting

Validate Your Changes

Before submitting, validate your JSON:

Using jq
Using Python
Using Node.js
Online Validator

# Validate JSON syntax
cat color-palettes.json | jq .

# If valid, this will pretty-print the JSON
# If invalid, you'll see an error message with line number

import json

with open('color-palettes.json', 'r') as f:
    try:
        data = json.load(f)
        print("✓ Valid JSON")
        print(f"Total protocols: {len(data)}")
    except json.JSONDecodeError as e:
        print(f"✗ Invalid JSON: {e}")

const fs = require('fs');

try {
  const data = JSON.parse(fs.readFileSync('color-palettes.json', 'utf8'));
  console.log('✓ Valid JSON');
  console.log(`Total protocols: ${Object.keys(data).length}`);
} catch (e) {
  console.error('✗ Invalid JSON:', e.message);
}

Pre-submission validation:

Submit Your Pull Request

Create a pull request with your changes:

# Commit your changes
git add color-palettes.json
git commit -m "Add [Protocol Name] color palette"

# Push to your fork
git push origin your-branch-name

PR Description Template:

## Adding [Protocol Name]

**Protocol**: [Full Protocol Name]
**Primary Color**: [#HEXCODE]
**Source**: [Link to official brand guidelines]

### Aliases Included
- `alias1` - [Reason for inclusion]
- `alias2` - [Reason for inclusion]
- `alias3` - [Reason for inclusion]

### Verification
- [ ] Verified color from official source
- [ ] Tested aliases in Dune queries
- [ ] JSON validated locally
- [ ] No alias conflicts detected

Monitor CI Checks

Once submitted, automated CI checks will run:

JSON Schema Validation

Validates your entry against the schema

Duplicate Alias Detection

Checks for conflicts with existing aliases

If CI checks fail, see CI Validation Checks for troubleshooting guidance.

Real-World Examples

Example 1: Adding a New Layer 2

Scenario: Adding Optimism to the collectionResearch:

Official site: https://optimism.io
Brand color: #FF0420 (from brand kit)
Common names: “Optimism”, “OP Mainnet”, “OP”

Entry:

"Optimism": {
  "hex": "#FF0420",
  "aliases": ["optimism", "op mainnet", "op"]
}

Result: ✅ Successfully added

Example 2: Adding a DeFi Protocol

Scenario: Adding Lido staking protocolResearch:

Official site: https://lido.fi
Brand color: #4DB0F2 (from CSS)
Common name: “Lido” (ticker: LDO, but we use protocol name)

Entry:

"Lido": {
  "hex": "#4DB0F2",
  "aliases": ["lido"]
}

Result: ✅ Successfully added

Example 3: Adding a Protocol with Special Characters

Scenario: Adding 1inch DEX aggregatorResearch:

Official site: https://1inch.io
Brand color: #0077FF
Common names: “1inch”, “oneinch” (spelled out), “inch”

Entry:

"1inch": {
  "hex": "#0077FF",
  "aliases": ["1inch", "oneinch", "inch"]
}

Note: Numbers are allowed in protocol names and aliasesResult: ✅ Successfully added

Example 4: Handling Alias Conflicts

Scenario: Adding Sei, but “sei” alias might conflictResearch:

Checking existing entries: Found “SEI (Cosmos)” with aliases ["sei cosmos", "sei network"]
This is a different Sei implementation

Entry:

"Sei": {
  "hex": "#9E201B",
  "aliases": ["sei"]
}

CI Check: ❌ Would fail - “sei” conflicts with context in “SEI (Cosmos)”Resolution: Use more specific aliases or discuss in PRSee Understanding Alias Conflicts for resolution strategies.

Common Mistakes to Avoid

Invalid Hex Codes❌ "hex": "627EEA" - Missing # prefix❌ "hex": "#627" - Too short (must be 6 digits)❌ "hex": "#627EEAFF" - Too long (no alpha channel)❌ "hex": "#627eea" - Lowercase is allowed but uppercase preferred✅ "hex": "#627EEA" - Correct format

Empty or Invalid Aliases❌ "aliases": [] - At least one required❌ "aliases": ["eth", "eth"] - No duplicates allowed❌ "aliases": ["eth/weth"] - Invalid character /✅ "aliases": ["eth", "weth"] - Correct format

JSON Formatting Errors❌ Missing comma between properties❌ Trailing comma after last entry❌ Unquoted property names✅ Properly formatted with all required syntax

Getting Help

If you encounter issues while adding colors:

Review the Contribution Guidelines for general best practices
Check CI Validation Checks if automated tests fail
Read Understanding Alias Conflicts for conflict resolution
Open a discussion issue if you’re unsure about anything

The community is here to help! Don’t hesitate to ask questions in your pull request.

Getting Started

Using Color Palettes

Schema

Contributing

Reference

Adding New Protocol Colors

Understanding the Schema

Schema Properties

Step-by-Step Process

JSON Schema Validation

Duplicate Alias Detection

Real-World Examples

Common Mistakes to Avoid

Getting Help

​Understanding the Schema

​Schema Properties

​Step-by-Step Process

JSON Schema Validation

Duplicate Alias Detection

​Real-World Examples

​Common Mistakes to Avoid

​Getting Help

Understanding the Schema

Schema Properties

Step-by-Step Process

Real-World Examples

Common Mistakes to Avoid

Getting Help