Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
516 lines (415 loc) · 37.1 KB

CONTRIBUTING.md

File metadata and controls

516 lines (415 loc) · 37.1 KB

Contributing

Thank you for taking the time to read and contribute to our project!

This documentation is long and comprehensive, because we strive for high quality for our icons and want to minimize extra work as much possible.

Warning
For contributing, you must know basics of making / editing vectors with vector graphics editor (see the software section).
There's instructions for some steps, but not for everything.

Note
It's highly recommended to also have some knowledge of graphic design and design in general.

Table of contents

Icon acceptability criteria

Before making or requesting an icon for app / site, please check if it fits our "acceptability criteria".

Approved

✔️ Almost always accepted to request or submit.

  • Apps / sites that are popular and has Aegis supported 2FA support (specially wanted).
    • Examples (not limited to): social media, productivity tools, cloud services, development tools, gaming related etc.
  • Almost any app / site / service, that doesn't have the exceptions from below.
    • Still in spite of this, aegis-icons has right to reject requests or submissions if needed or necessary.

Case-by-case basis

❔ Needs some examining before accepting or rejecting. Request or submit and we will tell if it's accepted or not.

  • Forums, message groups.
    • We rather make icons based of the forum softwares, because those are more universally usable for users then specific communities.
    • Exception: really popular forums can get their own icons (at least over 250,000 total members and high posting activity).
  • Platforms that icon requester / submitter is the creator or owner of the platform itself.
    • We don't do free work or want self-advertising here.
    • Exception: if platform is actually popular and has potential users for Aegis.
  • Self-hosted or similar software.
    • Suggested to have ≥ 500 GitHub / Gitlab stars or other non-maintainer activity to back it up.
    • If things previously mentioned aren't available, then we measure popularity based of search results.
  • Adult content, piracy & gambling related sites / apps / services.
    • Mostly okay here, but it cannot break any of the "not approved" bullet points.
  • App / site being too vague.
    • Examples (not limited to): site only has login page and nothing else, search results don't answer what that app / site is either.
    • It's not enough that you tell what the app / site does, we need at least some evidence from the web. Otherwise it counts to shady apps / sites category.
  • Ad networks.
    • Most of them belongs to shady apps / sites category, because often these services violate privacy on other users expense and trick users for unwanted things.
    • Exception: ad networks with ethical standpoints (minimal or no user tracking / data collecting, no dark patterns, high advertiser monitoring etc).

Not approved

❌ These are never accepted to aegis-icons, no exceptions!

  • Apps / sites not having Aegis supported 2FA support.
    • Also when service has officially discontinued 3rd party 2FA support (only supporting legacy users) and no known workaround for new users.
  • Platforms having massive hate speech group following and poor moderation (a.k.a. "Alt-tech").
  • Obvious scams or other shady apps / sites.
  • Apps / sites focusing on highly immoral and illegal activity / material.
    • Examples (not limited to): black hat hacking, malware, malvertising, money laundering, illegal sexual material / services, harassment / cyberbullying etc.
  • ⚠️ Only for icon submissions: submitting unmodified SVGs / raster images from the web.
    • You'll need to design the icon yourself for submissions!

Icon creation walkthrough

Software

Lists of softwares that are suitable for making vectors (and opposite).

Allowed

✔️ Most used and approved software.

We recommend these because the maintainer can give advice / help for these softwares:

  • Adobe Illustrator (industry standard, most used software in this repository)
  • Affinity Designer (way cheaper but powerful and better alternatives to Illustrator)
  • Figma (more known as interface design tool, but has good enough vector functions for making icons as well)
  • Inkscape (popular open source option)

If your software isn't listed in here or prohibited section, check your software's website.

If it mentions being "vector graphics editor" (and not "photo / image editor"), then it most likely is okay as long as it can save vectors as SVG.

Note
If your software is outside of the mentioned list, then we cannot give you help or support for your vector creating problems.

Prohibited

❌ Some of the softwares we don't approve, change to one of the allowed softwares or cancel the making of the icon.

  • Adobe Photoshop
  • Affinity Photo
  • Clip Studio Paint
  • GIMP
  • Krita
  • Paint.NET
  • (And more...)

These softwares are mostly for photo / image editing and aren't designed for vector creating.

Some of the softwares might have some basic vector editing capabilities, but aren't good enough for e.g. combining logos into one path or creating SVGs without lot of bloat code.

Repository submitting options

Before creating icons, you have decide which way you want to submit your icon creations:

Filling requests

To ensure that icons have been made correctly based of the CONTRIBUTING guidelines, we require all the contributers to create submission issue or pull request for filling requests (excludes organization members).

Finding source images

Search through the logo resources to find a vector-based image (SVG, AI, EPS, PDF).

Warning
Never use JPG / PNG / GIF / WebP or other raster images (as is)!

Here are things you can check, go these options in order:

  • Press kit on the company website
    • Eg. Zenkit has "Press Kit" page, that has ZIPs containing vector-based logos.
    • Look for pages like: Brand(ing), Press, Media, Logos, Assets, Marketing, About etc.
      • Trying googling too: logo site:offical-site-for-app-or-site.com
  • Embedded logo(s) on company website
    • Easiest way for finding / downloading SVGs from web pages is using SVG Gobbler browser extension (Chrome & Firefox, open source).
    • Ways without extension:
      1. Try right-clicking logo image and selecting Save image as..., and see if the save dialogue appears with SVG (not as JPG, PNG, GIF, WebP or any other raster graphic format).
        • If right-clicking the image does not have an option for Save image as..., try using Inspect at the bottom of the right-click menu. This opens the developer tools which can reveal hidden URLs.
          • Eg. at Codeberg, inspecting the logo in the left side of the navigation or logo at center reveals the location of SVG. Right-click and "open in new tab" to see the SVG file.
          • Sometimes SVG is embedded as inline. Means that instead of linking to external file, whole SVG file code is added to the HTML site code (see SVG code example). In that case, copy the SVG code completely from HTML (website embedded SVG starts with <svg & so forth and ends with </svg>), open your refer text editor and save copypasted text as filename.svg. You can test if the file works by opening in it into web browser (drag-and-drop SVG to tab bar or shortcut: Ctrl [⌘ Cmd]+O).
      2. Right-click the website and select View page source, then press Ctrl [⌘ Cmd]+F to open the search tool and type SVG to look for possible SVG vector files. Web inspector is also useful and better tool for some users / use cases (press F12 on the website, go to "Inspector" / "Elements" tab, then press Ctrl [⌘ Cmd]+F to search).
        • Eg. You Need A Budget reveals the hidden SVG resource in HTML metadata section (https://www-assets.youneedabudget.com/wp-content/themes/dupatta/dist/images/safari-pinned-tab_[alphanumerical-string].svg) which can be copy-paste into the browser and save (Ctrl [⌘ Cmd]+S).
  • If everything has failed so far, then check logo resources section.
    • Remember though, logo has to be latest one that company uses.
  • As last resort, you can try image tracing with raster images (JPG, PNG etc). Rule of thumb with image tracing is using image that's high resolution, not many colors and doesn't have any artifacts (if image does have artifacts, you can try Pix Fix tool to remove them).
    • Vectorizer.io is great image tracer, but vectors aren't freely downloadable anymore. Generating vectors without account / freely is still possible.
      • There's a loophole to download the SVG: use SVG Gobbler after vector is generated.
        • Alternatively: Inspect the output image (Ctrl [⌘ Cmd]+Shift+C) and copy the SVG code from dev tools.
    • Vector Magic is the one of best – if not the best – image tracer.
    • Illustrator & Inkscape has image tracing tools, but we really don't recommend them. Usually results varies from really bad to somewhat decent.
  • Making vectorized logo from scratch is also option, if you're skilled and patient enough.

Note
Is the SVG file broken? SVG compression with SVGO or SVGOMG might just fix it.

Warning
Watch out for SVGs that are using raster graphics (example). These are not common, but does exist.

Templates

When making icons, download and use provided templates.

  • For Illustrator, use ai_template.ait (for primary icons) or ai_template_generic.ait (for generic icons).
    • .ait is Illustrator template file format, don't save over template file! (Read save and export for more info).
  • Other softwares, use svg_template.svg (for primary icons) or svg_template_generic.svg (for generic icons).

Layout

Icon grid

Documentation coming soon...

Vectors

  • ⚠️ Logo must be in single path / compound path / object:
In Adobe Illustrator (click to reveal)
  1. Open Layers window, if it's not already open (shortcut: F7 or menu: Window ➜ Layers)
  2. Ungroup all the layer groups related to the logo completely.
    • "Target select" the layer group in Layers window by clicking "circle" (○) on the right (Shift+Click to select multiple groups).
    • Press Ctrl [⌘ Cmd]+Shift+G multiple times until everything is ungrouped.
  3. Keep all the logo parts "target selected" and make compound path (menu: Object ➜ Compound Path ➜ Make or shortcut: Ctrl [⌘ Cmd]+8).
    • If compound pathing doesn't work, open Pathfinder window (menu: Window ➜ Pathfinder or shortcut: Ctrl [⌘ Cmd]+Shift+F9) and press "Unite" (top-left icon in the window under "Shape modes" text).
In Affinity Designer (click to reveal)
  1. Open Layers window, if it's not already open (menu: View ➜ Studio ➜ Layers).
  2. In canvas, use "Move" tool (V) and select logo layers by click & drag across the logo (avoid selecting circle).
  3. Ungroup multiple times until everything in the logo is ungrouped (Ctrl [⌘ Cmd]+Shift+G).
  4. Unselect everything (click outside of canvas with "Move" tool).
  5. Repeat step 2.
    • ℹ️ Before moving to step 6, read and do "Note for Affinity Designer users" part downwards.
  6. Combine logo (menu: Layer ➜ Geometry ➜ Add).
In Inkscape (click to reveal)
  1. Open Objects window (menu: Object ➜ Objects).
  2. Select all the objects related to logo (Shift+Click in the Objects window).
  3. Ungroup the object multiple times until everything is ungrouped (menu: Object ➜ Ungroup or shortcut: Ctrl [⌘ Cmd]+Shift+G).
  4. "Union" the objects to together (menu: Path ➜ Union).

Note – For Affinity Designer users:
Change "fill mode" of the logo vector and its parts from "Winding (Non-Zero)" into "Alternative (Even-Odd)" (menu: Layer ➜ Fill Mode). Otherwise it creates CSS rules we don't want for our SVGs and we want everything to contain by the vector path.

Colors

  • Never use white as background (abbreviation: BG), white is always preserved for logo (a.k.a. foreground, short for FG).
  • Don't pick random colors, unless there's absolutely no other options.
  • Don't use gradients, use solid colors.
  • Keep everything at 100% opacity, no blending etc.
  • Logo / FG should always use white (#FFFFFF).
    • Exceptions: fg.var & fg.bg.var icons.
  • If you find brand guideline that has documented brand colors (example [wayback machine]), then go with that. For background color, use primary brand color that has specifically said on the guideline or based on what color is used most.
  • If there's no guidelines and logo only has one color, use logo color as icon background.
    • For multi-color logos, pick the best looking or most used color.
      • Tip: In Illustrator, if logo is using gradient, use this method [wayback machine] to extract all the colors in the gradient to the swatches.
  • If icon you're making is using dark background, you have to make bg.var icon version as well.
    • Or opposite, if background is too bright for white logo, then make fg.var icon version.
    • Check with "BG colors to avoid" SVG if bg.var version is needed.
  • For generic icons, use templates (ai_template_generic.ait or svg_template_generic.svg) and don't change the BG colors!

bg.var, fg.var & fg.bg.var icons

Note
var is abbreviation of variation.

  • bg.var icons are for dark / AMOLED themes. These are made when primary icon has dark background that blends in when using the darker theme.

  • fg.var icons are made when primary icon's BG color is too bright and hard to see with white logo.

  • fg.bg.var is combination of both variations, for edge cases when bg.var BG color is too bright and makes white logo hard to see.

Alternative icons

"Alternative" – in this case – means icons for brands that provide alternative logos of their brands.

Just change the logo for alternative version.

Generic icons

"Generic" – in this case – means icons that doesn't represent any brand and are using symbol-like vectors.

  • Use ai_template_generic.ait or svg_template_generic.svg template, depending on the software.
  • Don't change the background color of the template (#6750a42).
  • Foreground color is always white (#FFFFFF).
  • Use these icon libraries:

Save and export

Note
Please read the info about naming at the filename section.

  • If you're using Adobe Illustrator CC 2017 or newer, save the file as SVG with "Export for Screens" option (shortcut: Ctrl [⌘ Cmd]+Alt [⌥ Option]+E or menu: File ➜ Export ➜ Export for Screens...) with these settings.
  • For other softwares:
    • Before saving final version, remember to remove the guide strokes!
    • In Affinity Designer, export file with "SVG (digital - small size)" preset.
      • We also recommend saving it (temporarily) to afdesign file format for making edit requests faster and easier to do.
    • In Inkscape, save the file as "Optimized SVG". (:warning: Hugely important!)
    • In software that's non-above, save as "SVG" or "Plain SVG", whichever is the safest available option.
  • ❌ Don't make PNG files! PNG files are legacy content (with some exceptions).
  • If you're submitting pull request, read also the directories section.

Next, do SVG compression & cleanup.

SVG compression & cleanup

If you're comfortable with command line tools:

  • Install Node.js and SVGO
  • Use this command: 
    svgo --multipass --pretty --indent 3 -f "input/folder/path/here" -o "output/folder/path/here"
    (Or if you're in Windows, we have batch file for this).

If you don't know how to use command line:

  • Use SVGOMG
    • Just tick "Prettify markup" before downloading the compressed SVG.
    • Don't make other changes to settings.

⚠️ After SVGO or SVGOMG step, check / manually edit with text / code editor (Notepad, TextEdit, Vim etc.) that SVG is correctly formatted for submission:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024">
   <circle cx="512" cy="512" r="512" style="fill:#BG-HEX-COLOR"/>
   <path d="PRETTY-LONG-LOGO-PATH" style="fill:#LOGO-HEX-COLOR"/>
</svg>

▲    SVG code formatting example

  • 🗒️ Checklist for SVG formatting:
    • Check that the indentation is 3 spaces (important if you used SVGOMG).
    • Check that the order of all the elements and attributes is EXACTLY same as the SVG code formatting example.
    • Check that possible fill=" prefixes are changed to style="fill:
    • Remove all the elements and attributes that aren't featured in the SVG code formatting example.
    • See the example SVG code after manual cleanup for aimed optimal result.

Note
Test the SVG on the web browser that it still works after edits! (drag-and-drop SVG to tab bar or "Open File..." shortcut: Ctrl [⌘ Cmd]+O).

When everything is done and ready to go, submit icons with either as pull request or issue.

Technical

Directories

  • Primary icons ➜
    • /icons/1_Primary/ folder.
    • Means all the logo based icons that aren't variations / alternatives.
  • Variation and alternative icons ➜
    • /icons/2_Variations/ folder.
  • Generic icons ➜
    • /icons/3_Generic/ folder.
  • For the outdated icons, see the new versions, version naming and organizing old files section.

Filename

Warning
When naming brand based icon(s), check how brand capitalised and spell the name from their app / website (check the capitalization / spelling from browser tab title or body text of their website, not from the logo!).

Note – Filename character limitations:
Only use ISO basic Latin alphabet letters, numbers, spaces, dashes and other safe ASCII characters (list of forbidden ASCII).

  • Primary icon:
    • [Company / product / app / site name].<ext>
    • Examples: Adobe.svg, Best Buy.svg, FACEIT.svg, itch.io.svg
  • Icon variations with alternate logo:
    • [Primary icon name] alt.<ext>
    • Example: IVPN alt.svg
  • Icon variations with black foreground or different background color:
    • [Primary icon name] bg.var.<ext>
    • [Primary icon name] fg.var.<ext>
    • Examples: Squarespace bg.var.svg, Snapchat fg.var.svg
  • Icon variations with black foreground and different background color:
    • [Primary icon name] fg.bg.var.<ext>
    • Example: Lichess fg.bg.var.svg
  • Alt. icons with black foreground or/and different background color:
    • [Primary icon name] alt bg.var.<ext>
    • [Primary icon name] alt fg.var.<ext>
    • [Primary icon name] alt fg.bg.var.<ext>
    • Example: Discourse alt bg.var.svg
  • Generic icon:
    • Name as what the icon symbolizes with big capital letter.
    • Example: Cloud.svg

New versions, version naming and organizing old files

  • New versions of icons are only made when it's major change (new logo or brand color).
    • Logos with only barely noticable brand related changes with same brand color (example by T-Mobile), doesn't need new icon version.
  • Icon files that are outdated for the first time, v1 is added to end of the filename.
    • Examples: Codeberg v1.svg.
  • Version label number increases for outdated icons when new versions of the primary icon are released (v2, v3, v4, v5 etc.).
  • Outdated versions are moved to directory: /icons/4_Outdated/.
  • ⚠️ Only for maintainers: Icons of now dead service (or didn't have 2FA etc.) should be moved to aegis-icons / misc's removed_icons directory just as is.
    • Also add info to the directory's README on why icon was removed.

About PNGs

As of 2021-07-25, aegis-icons doesn't actively make PNG icons anymore.

Instead, PNGs are only made when noticing problems with SVG on Aegis and are added to aegis-icons / png-files repo. PNGs are only made by maintainers to keep files & compressions consistent.

List of SVG icons with known rendering issues and PNG counterparts are available here.

About JSONs

Warning
Please do not submit PRs that make changes to JSON files!

Because of the JSON update process, currently only the maintainer (@krisu5) is allowed to make changes to JSONs.

If you want to suggest a change related to JSONs, make a issue instead (choose "Other").

Resources

Resources marked with star (:star:) are recommended / most used by the maintainers.

Logos

Resources for finding logos in vector format, when no official brand kit / vector logos are available.

Warning
Remember to always double check if logo provided by these resources is the latest one company uses!

More resources at LogoSearch's "Alternative Logo Sources" list.

Google tips for searching logos

  • logo site:offical-site-for-app-or-site.com
  • filetype:pdf site:offical-site-for-app-or-site.com (you can rip vectors from PDF, really often logos in these PDFs are vector).
  • "app-or-site-name-here" svg or "app-or-site-name-here" vector.

Lists of sites supporting 2FA

Need to check if service has 2FA? These list apps / websites that support 2FA and in what kind of format.

Google search queries for double-checking 2FA support

"app-or-site-name-here" AND 2fa OR mfa OR otp OR totp OR factor authentication OR step verification OR time-based one-time

or

site:official-domain-of-the-app-or-site.com 2fa OR mfa OR otp OR totp OR factor authentication OR step verification OR time-based one-time

Issue guidelines

(Issue guidelines was last updated on: 2022-10-26)

  1. App / site related requests has to have Aegis-compatible 2FA support one way or another, this project does not make icons outside of Aegis usage.
    • Don't lie, we always double-check if requested service has 2FA support. You can add proof for the existence of Aegis-compatible 2FA to the issue form's "Proof of the Aegis-compatible 2FA" section.
      • For the similar icons for general purpose, check out Simple Icons instead.
  2. Check that icon you're about to request doesn't already exist or opened / closed in the issues.
    • Icon packs are updated monthly, not every time a new icon is created (see the pack releases). Icons created after the latest pack update are downloadable on the website.
  3. Read the issue form carefully and follow the instructions.
  4. Don't open more then 5 icon request issues at the same time.
    • You can request more after all of your current requests are filled.
  5. Aegis-icons can reject any icon request for any reason, but most of the requests gets filled. Usually we do provide explanation and possibly alternative option if we reject the request.
    • Possible reasons for rejections (among others):
      • App / site not offering Aegis supported 2FA in the first place.
      • Forum not popular enough (forum software related icon is the alternative).
      • No high quality logo resources available.
    • More info about approved & unapproved types of apps / sites.
  6. If you have question or miscellaneous suggestion, check out FAQ first.
  7. Be respectful to the maintainers and contributers.

Footnotes

Here's all the footnotes:

Footnotes

  1. Article: Logo, Logomark, Logotype - What's The Difference And What Do You Need? [wayback machine] ↩ ↩2

  2. This color is taken from Material Design 3's color system (token: Primary40, hex: #6750a4). ↩