ICONIC turns a skills row into a row of bubble-shaped SVGs

A skills row, designed rather than assembled

ICONIC is a developer-oriented library of sleek, bubble-shaped skill icons designed for GitHub READMEs, portfolios and resumes. The line in the README is short: be iconic, not generic.

The problem it addresses is a small but real one. Every developer has a skills section in their README, and the standard solutions are badge services that render a flat rectangle of text and a logo, all the same size, all the same visual weight, in a row that looks like a wall of labels. ICONIC's answer is a different shape. The icons are bubbles, and the set is explicitly dev-focused, which is what separates it from a generic icon library.

The feature list is short. There are bubble icons designed for clarity and aesthetics, light and dark theme variants for every icon, icons that are easy to embed in Markdown, HTML or anywhere, an HTML preview API with a Django backend, and download-ready SVGs.

Two of those five features are what the project actually is. The light and dark pairing matters because a README is read on GitHub in both themes, and an icon set that only works on one of them looks broken half the time. The download-ready SVGs matter because they are the escape hatch from the hosted service, and a project like this lives or dies on whether someone can use it without a network round trip.

The audience is a person building a personal profile: a developer README, a portfolio site, a resume. The repository topics list matches that, with github-profile-readme, portfolio, skill-icons, badges-markdown and icon-pack among them.

The URL is the API

The way to use an icon is to point an image tag at it. The hosted service is at iconic-api.onrender.com, and the path structure is a theme and a name:

## HTML

<!-- Use div tag for good format and it will show them in one line, without div tag it will be displayed on multiple lines -->
<div style="display: flex; gap: 2px; align-items: center;">
<img src="https://iconic-api.onrender.com/dark/python" width="64px" />
<img src="https://iconic-api.onrender.com/dark/html" width="64px" />
<img src="https://iconic-api.onrender.com/dark/js" width="64px" />
<div>

So dark/python returns the dark variant of the Python icon, and light/dart returns the light variant of Dart. The same pattern appears in the larger samples further down the README, where the icons are given title attributes such as title="Python (Dark)" and title="Docker (Light)", which is what produces a tooltip on hover.

The names in the samples cover a fairly wide spread of a developer's toolkit: Python, HTML, Dart, CSS, Git, GitHub, Linux, VS Code, Docker, Bash, Figma and Node.js.

The URL scheme is the whole integration surface. There is no client library, no build step and no configuration, which is exactly right for a README, where a three line snippet is the only realistic thing anyone will actually paste.

The one thing to notice is that the path has no version segment. Whatever the service serves at that slug is what your README will show, so a change to an icon upstream is a change to your page, without a commit on your side.

Why the README pushes the HTML snippet over plain Markdown

GitHub renders Markdown, and Markdown image syntax does not let you control layout. The README addresses this with a note, and it is the most practically useful piece of advice in the file.

It is recommended to use the HTML snippet in GitHub READMEs, as it allows better control over size, styling, and layout. The inline comment in the sample says the same thing from the other direction: use a div tag for good format and it will show them in one line, without the div tag it will be displayed on multiple lines.

That difference is real and visible. A row of Markdown image links, one per line, renders as a column or as an awkwardly wrapped set, depending on the width. The div wrapper with display: flex, gap: 2px and align-items: center puts the icons in one row with a consistent two pixel gap and vertically aligned centres, and the width attribute on each image sets the size.

The tradeoff is that you are opting out of pure Markdown for that section of the file. GitHub sanitises the HTML it renders, so inline style attributes on a div and on img elements are the part that works, while anything more elaborate will be stripped. The project's own samples stay inside that limit, which is a good indication of where the boundary is.

For a portfolio or a resume rendered as HTML, the same snippet works and the flex layout is the right default there too.

Running the Django service locally

The project is a Django application that serves the icons, and the getting started section gives the full local setup. The steps are to clone the repository, change into the project folder, optionally create and activate a virtual environment, install the dependencies from requirements.txt, and run the Django development server:

git clone https://github.com/YuheshPandian/ICONIC.git
cd ICONIC
python -m venv venv
pip install -r requirements.txt
python api/manage.py runserver

On Linux and Mac the virtual environment is activated with source venv/bin/activate, and on Windows with the Scripts activate command.

The server then exposes four things. The index page is at http://localhost:8000/, the Icon Gallery is at http://localhost:8000/gallery/, and the two icon endpoints are the query to get the dark icon file at http://localhost:8000/dark/[icon_name] and the same for light at http://localhost:8000/light/[icon_name]. The gallery is the practical part for a contributor, since it shows the whole set in one place.

The dependency list is small and fully pinned, which is the shape you want from a service that renders a README: asgiref, Django at 5.2.1, django-cors-headers, gunicorn, packaging, sqlparse and tzdata. The presence of gunicorn is the deployment story, and the CORS headers are there because the icons are fetched by a browser from a page on another origin, which is exactly the case where a browser would otherwise block them.

Adding an icon means editing SVGs twice

The contributing section describes a workflow that is deliberately manual, and the reason is that these are hand-made SVGs rather than generated glyphs.

You create your icon using a photo editing software, with Inkscape preferred, and open the dark and light icon template to start editing. You then add the dual versions of the icon in the respective dark and light folders, and push the changes if completed.

The repository layout matches that workflow. There is an icons/ directory with dark and light subdirectories, a separate icon-templates/ directory holding the files you start from, an api/ directory for the Django service, an assets/ directory for the images used in the README itself, and a scripts/ directory.

The conventions are stated in one line and they are the difference between an icon pack that looks coherent and one that does not: follow the existing folder structure of dark/ and light/, keep icon dimensions consistent, for example 512x512 SVG, and use meaningful file names.

The two-file requirement is the cost of the dark and light variants, and the 512 by 512 requirement is what lets a row of icons sit at different display sizes without re-authoring. Whether a bubble shape reads well at 24 pixels in a README sidebar is a separate question from whether it reads well at 512, and the template is what carries the design between those two sizes.

Hosted images against committed SVGs

There are two ways to use ICONIC, and the README supports both, which is the right call.

The first is the hosted URL, an img tag pointing at the API. The advantages are obvious. Your README stays small, because you are not committing binary or vector assets, and adding a skill to your list is a one line change that does not need a second commit for the assets. The cost is a network dependency on a third-party service for every page view, and a page that renders a blank row if that service is slow or down.

The second is the download-ready SVGs, committed into your own repository. The advantages are the mirror image. The icons render with no third-party request, they work in an offline clone of your README, and the asset is yours. The cost is repository weight and a commit every time your skills list changes.

The design decision that makes the second option work is the dark and light folder structure. You copy the two variants of an icon into your own repository, and the theme selection happens in the markup, not in the file, so the same pair of files serves both GitHub themes.

For a portfolio or a resume that you might send to someone as a PDF, or for a README that is read in a mirrored or offline environment, the committed SVG is the more dependable choice. For a GitHub profile README, which is read on github.com and nowhere else, the hosted URL is the tidier one.

Maintenance, licence and what to check before you paste the snippet

The licence is MIT, with the LICENSE file at the repository root, and the README links it directly. For a set of icons that you embed in a public profile, that matters: you can use them, modify them, put them in your own repository, and ship them in a portfolio, without the licensing conversation that a non-commercial asset licence would trigger.

The maintenance picture is modest. The last push was on 2026-08-07, the repository is not archived, and there are no GitHub releases, so the artefacts are the files in the repository and the images served by the hosted API rather than a tagged version. The README carries badges for the icon count in the dark directory and for the repository size, and the issues badge is filtered to the icon label, which suggests icons are requested and tracked as labelled issues.

Three things to verify before you commit a skills row to a page you will keep for years.

First, that the hosted endpoint actually returns an image for the slugs you want, since the path is a plain name and a missing icon will render as a broken image rather than an error. Second, that the light and dark variants look right next to each other, because a mismatched pair is more noticeable than a single icon. Third, that you are comfortable with the URL having no version segment, which means the icon you see today is not guaranteed to be the icon you see after the service updates it.

And if the set does not cover the skill you want, the contribution path is a template and two files, which is a low bar for adding it.

Editorial conclusion

ICONIC suits an individual developer or a portfolio owner who wants a skills row that looks designed rather than assembled from whatever badge service happened to be popular, and who is happy to reference a hosted API for the images. It is the wrong choice if your README must render without network access, if you need icons in a colour scheme other than the two provided, or if you need a stable versioned asset URL. Verify first that the hosted endpoint responds for the icon names you want, since the URL scheme is a plain slug with no version segment, and check the light and dark variants side by side before you paste the snippet into a README that will be seen for years.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. YuheshPandian/ICONIC on GitHub