Create / Submit Icon Pack

Overview

This document provides comprehensive guidance on creating an icon theme package using the specified JSON structure. The icon theme system allows developers to define and distribute custom icon packs with associated metadata and icon mappings.

Schema Structure

Root Level Properties

• iconPack (string): The name of the icon pack
• iconPackVersion (string): Version number of the icon pack following semantic versioning
• iconProvider (string): Unique identifier for the icon provider, typically in reverse domain notation
• baseUrl (string): Base URL for icon assets
• baseUrlLight (string|null): Optional base URL for light theme variants
• packDeveloper (string): Name of the pack developer
• credit (object): Attribution information for the icon pack
  • name (string): Name of the original icon pack/creator
  • url (string): URL to the original source

Icon Data Structure

The iconData array contains objects with the following properties for each icon:

• iconId (string): Unique identifier for the icon
• iconUrl (string): Relative path to the icon file from the baseUrl
• iconName (string): Display name for the icon
• iconUrlLight (string|null): Optional relative path for light theme variant

Implementation Guide

1. Basic Setup

   {
     "iconPack": "Your Pack Name",
     "iconPackVersion": "1.0.0",
     "iconProvider": "com.yourdomain.iconpack",
     "baseUrl": "https://your-cdn-url/icons",
     "baseUrlLight": "https://your-cdn-url/icons/light",
     "packDeveloper": "Your Name"
   }

2. Adding Credits

   {
     "credit": {
       "name": "Original Pack Name",
       "url": "https://original-source.com"
     }
   }

3. Adding Icons

   {
     "iconData": [
       {
         "iconId": "unique-id",
         "iconUrl": "/folder/icon-name.svg",
         "iconName": "Display Name",
         "iconUrlLight": "/folder/icon-name-light.svg"
       }
     ]
   }

Best Practices

1. Icon IDs

   • Use lowercase alphanumeric characters
   • Avoid spaces (use hyphens or underscores)
   • Keep IDs short but descriptive
   • Ensure uniqueness within the pack

2. URLs

   • Use CDN URLs for better performance
   • Ensure URLs are permalinks
   • Use relative paths in iconUrl
   • Test URL accessibility

3. Versioning

   • Follow semantic versioning (MAJOR.MINOR.PATCH)
   • Update version when adding/removing icons
   • Document changes in a changelog

4. Icon Names

   • Use proper capitalization
   • Be descriptive but concise
   • Include brand name if applicable

Validation Checklist

• All required fields are present
• JSON is valid and properly formatted
• All URLs are accessible
• Icon IDs are unique
• Version number follows semantic versioning
• Credit information is accurate
• Icon names are properly formatted
• Base URL is secure (HTTPS)

Example Implementation

{
  "iconPack": "Devicon",
  "iconPackVersion": "1.0.0",
  "iconProvider": "com.astroluma.devicon.dev",
  "baseUrl": "https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons",
  "baseUrlLight": null,
  "packDeveloper": "Sanjeet990",
  "credit": {
    "name": "Devicon.dev",
    "url": "https://devicon.dev/"
  },
  "iconData": [
    {
      "iconId": "threedsmax",
      "iconUrl": "/threedsmax/threedsmax-original.svg",
      "iconName": "Autodesk 3ds Max",
      "iconUrlLight": null
    }
  ]
}

Error Handling

Common errors to watch for:

1. Invalid URLs

   • Ensure all URLs are properly formatted
   • Verify CDN accessibility
   • Check for broken links

2. Duplicate IDs

   • Maintain unique iconId values
   • Use a validation script to check for duplicates

3. Missing Required Fields

   • Verify all required properties are present
   • Check for null values where not allowed

Submit Icon Pack

Once you're done with the icon pack, next step is to submit the icon pack to be hsoted on the Astroluma Portal. To do this send an email to [email protected] attaching the icon pack.