Best Practices - Color Palettes

Follow these best practices to maintain consistency in your visualizations and contribute effectively to the Color Palettes project.

Using Color Palettes

Automatic Color Matching

Color Palettes automatically applies brand colors to your Dune visualizations when protocol names are detected in your query results.

Colors are matched using protocol aliases (case-insensitive). The system automatically detects and applies the correct colors based on your data.

How Matching Works

Considering this schema example:

{
  "Ethereum": {
    "hex": "#82828",
    "aliases": ["eth", "weth"]
  }
}

These will match:

Eth
eth
WeTh
evm_<color:eth> (special case allowing string prefixes)

These will NOT match:

ethereum (not in aliases)
evm<clor:eth> (typo in special syntax)
color:eth (missing prefix delimiter)

Customization Control

You have full control over visualization colors:

Override Colors

You can override any automatically applied color with your preferred choice directly in the Dune visualization editor.

Select the element in your visualization
Choose a custom color from the color picker
Your custom color will persist for that visualization

Restore Default Colors

Easily revert back to the standard Color Palettes at any time:

Open your visualization settings
Click the Restore colors button
All colors will be reset to the Color Palettes defaults

Visualization Best Practices

Maintain Consistency

Use the same colors for protocols across all your dashboards to help users quickly recognize patterns.

Consider Accessibility

Ensure sufficient color contrast for readability. Test your visualizations for color-blind accessibility.

Use Official Colors

Always use the official brand colors when available to maintain brand integrity and recognition.

Document Overrides

If you override colors for specific reasons, document why in your dashboard description.

Contributing to Color Palettes

The Color Palettes project is community-driven. Your contributions help maintain consistency across all Dune Analytics visualizations.

What You Can Contribute

Submit New Protocol Colors

Add colors for protocols not yet in the collection. Ensure you use the official brand color from the protocol’s brand guidelines.

Update Existing Colors

If a protocol has updated their brand colors, submit an update with a reference to the official brand guidelines.

Add New Aliases

Add common variations of protocol names to improve automatic matching in queries.

Report Inconsistencies

Found incorrect colors or aliases? Report them via GitHub issues.

Schema Requirements

When contributing, follow this JSON schema structure:

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

string

required

The official name of the protocol or chain. Use proper capitalization as shown in the protocol’s official branding.

string

required

The hex color code of the protocol’s primary brand color. Must be a valid 6-character hex code starting with #.

array

required

Common variations of the protocol name used in queries. Include:

Lowercase versions
Common abbreviations
Network variations (e.g., “uniswap_v2”, “uniswap_v3”)
Chain-specific names

Handling Alias Conflicts

Alias conflicts occur when the same alias is associated with multiple protocols.

The repository includes automated CI checks that will block pull requests with alias conflicts. Resolve these before your PR can be merged.

Common Conflict Examples

// ❌ This will fail CI
{
  "Binance Smart Chain": {
    "hex": "#F3BA2F",
    "aliases": ["bsc", "bnb"]
  },
  "Basis Cash": {
    "hex": "#000000",
    "aliases": ["bsc", "basis"]  // "bsc" already exists!
  }
}

// ✅ This will pass CI
{
  "Binance Smart Chain": {
    "hex": "#F3BA2F",
    "aliases": ["bsc", "bnb", "binance_smart_chain"]
  },
  "Basis Cash": {
    "hex": "#000000",
    "aliases": ["basis", "basis_cash"]  // Unique aliases
  }
}

Automated CI Checks

Every pull request runs automated validation to ensure:

Resolution Process

CI Detects Conflict

Automated checks run and identify the duplicate alias.

PR Blocked

Your pull request cannot be merged until the conflict is resolved.

Review CI Logs

Check the CI logs for specific details about which aliases conflict.

Resolve Conflict

Update your changes by:

Removing the conflicting alias
Using a more specific alias
Engaging in PR discussion if there’s a special case

Alias Best Practices

Research First

Before creating a PR, check existing protocols and their aliases to avoid conflicts.

Be Specific

Use specific, unambiguous aliases. When in doubt, use longer, more descriptive variations.

Include Variations

Add common variations of the protocol name:

Ticker symbols
Common abbreviations
Version numbers
Alternative names

Review CI Logs

When CI fails, carefully review the logs to understand exactly which aliases conflict.

Color Selection Guidelines

Use Official Brand Colors

Always reference the protocol’s official brand guidelines or press kit. Most protocols publish these on their websites.Where to find official colors:

Protocol website footer or “Brand” section
GitHub repository (often in /assets or /branding)
Official press kits or media resources
Protocol documentation sites

Verify Color Accuracy

Double-check that the hex code matches the official branding:

Visit the protocol’s official website
Use browser developer tools to inspect brand elements
Cross-reference with official brand guidelines
Include reference links in your PR description

Handle Multiple Brand Colors

If a protocol uses multiple brand colors:

Choose the primary brand color (usually the most prominent)
Avoid gradients (use the main color from the gradient)
When uncertain, check how the protocol uses colors in their logo

Testnet vs Mainnet

For testnets or alternative network versions:

Use the same color as mainnet unless the protocol specifies otherwise
Add clear aliases to distinguish (e.g., “sepolia”, “goerli”)
Document in PR if using a variant color

Contributing Workflow

Fork the Repository

Fork the color-palettes repository on GitHub.

Edit color-palettes.json

Add or update protocol entries following the schema requirements.

Test Locally

Validate your JSON to ensure it’s properly formatted.

Submit Pull Request

Create a PR with:

Clear description of changes
Reference to official brand guidelines
Explanation for any alias choices

Respond to CI Checks

If CI fails, review the logs and make necessary adjustments.

Await Review

Community members and maintainers will review your contribution.

Small, focused PRs are easier to review and merge. Consider submitting separate PRs for different protocols.

Getting Help

If you encounter issues or have questions:

Open an issue on the GitHub repository
Join the Dune Discord community
Review existing PRs to see how others handle similar situations

The Color Palettes project relies on community contributions. Every contribution, no matter how small, helps improve the experience for all Dune Analytics users.

​Using Color Palettes

​Automatic Color Matching

​How Matching Works

​Customization Control

​Visualization Best Practices

Maintain Consistency

Consider Accessibility

Use Official Colors

Document Overrides

​Contributing to Color Palettes

​What You Can Contribute

​Schema Requirements

​Handling Alias Conflicts

​Common Conflict Examples

​Automated CI Checks

​Resolution Process

​Alias Best Practices

Research First

Be Specific

Include Variations

Review CI Logs

​Color Selection Guidelines

​Contributing Workflow

​Getting Help

Using Color Palettes

Automatic Color Matching

How Matching Works

Customization Control

Visualization Best Practices

Contributing to Color Palettes

What You Can Contribute

Schema Requirements

Handling Alias Conflicts

Common Conflict Examples

Automated CI Checks

Resolution Process

Alias Best Practices

Color Selection Guidelines

Contributing Workflow

Getting Help