713b1fcd25
* Add metadata information * improve contribution * feat(docs): added new contribution guide * feat(docs): minor linting fix * feat(docs): update dead link * feat(docs): change layout, some stylistic change, et cetera * feat(docs): alter metadata example layout * feat(docs): update titles, split use case & tag guide * feat(docs): finetune some design guide images & make * feat(docs): finetune some design guide images & add icons to use case guide * feat(docs): added ux writing instructions & proofread markdowns to match these guidelines * feat(docs): updated design language / specification descriptions to better distinguish what is what * feat(docs): updated design language / specification descriptions to better distinguish what is what * feat(docs): changed some languages again * fix(icons): add design principle do/dont about diagonal lines * fix(icons): decrease blurriness of ideal pixel perfection pixel preview * fix(icons): remove color from pixel perfection previews * fix(icons): remove color from pixel perfection previews * fix(icons): reword symmerical icon rule * fix(icons): fix calendar design in density rule image * fix(icons): slightly adjust centered stroke rule text * Rename 'useCases' property to 'use-cases' Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Update allowed SVG elements in code conventions Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Eric Fennis <eric.fennis@gmail.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
6.5 KiB
applyTo
| applyTo |
|---|
| icons/*.json |
JSON Metadata Descriptor
The schema for the JSON metadata descriptor can be found in icon.schema.json. It defines the required and optional properties for the JSON files that accompany each icon. The JSON metadata descriptor should be placed in the same directory as the SVG file of the icon and should have the same name as the SVG file, but with a .json extension. For example, if the SVG file is named home.svg, the JSON metadata descriptor should be named home.json.
Contributors
The contributors property is a required array of GitHub usernames for the people who created or contributed to the icon. It is used to give credit to contributors and to track the icon's history. Add the PR author to the contributors array if they are not already listed and they have made a significant contribution to the icon's SVG.
Tags
The tags property is an array of strings that describe the icon and can be used for searching.
Validate the tags against the icon.schema.json to ensure they are correctly formatted and adhere to the defined structure.
Provide tag suggestions based on the name of the icon and the use cases provided in the PR description. Use the existing tags in the repository as a reference for consistency and to avoid duplicates. Don't suggest words like: 'icon' and preferably use single words. Tags should always be in lowercase, and may also contain spaces (e.g. magnifying glass). The name of icon should not be included in the tags, as it is already specified.
Categories
The categories property is an array of strings that specify the categories to which the icon belongs, such as "devices", "interface", "media", etc. See the categories property in the icon.schema.json for more details on the allowed values. The categories should be chosen based on the use cases provided in the PR description and the existing categories in the repository. The categories should be relevant to the icon and should help users find the icon when searching for specific types of icons. The name of icon should not be included in the categories, as it is already specified. Suggest categories based on the name of the icon and the use cases provided in the PR description. Use the existing categories in the repository as a reference for consistency and to avoid duplicates. Categories should always be in lowercase and should not contain spaces.
Use Cases
The use-cases property is an array of strings that describe the specific scenarios in which the icon would be used. Each use case should be concise and clearly convey the context in which the icon is applicable. Use the existing use cases in the repository as a reference for consistency and to avoid duplicates.
Writing icon use-cases
A use-case tells a reader where and why an icon would be used in a real interface. Each entry should let someone who has never seen the icon understand what it's for.
Format
- Write each use-case as a short phrase, not a sentence. Start with a present participle verb: Representing…, Indicating…, Marking…, Showing…, Confirming…, Toggling…, Categorizing…, Searching….
- Keep it to roughly 4–12 words. One clear idea per entry.
- No trailing period. No leading bullet, number, or dash (the surrounding format supplies that).
- Give each icon 1–4 use-cases, ordered most-common first. Prefer fewer strong entries over many weak or repetitive ones.
Voice
- Write from the interface's perspective, describing the function: "Indicating a low battery charge level" — not the requester's story ("I need an icon that shows…").
- Name the concrete context where useful: in smart home apps, in navigation apps, in text editors, on maps. Context is what makes a use-case self-explanatory.
- Be neutral and factual. No first person, no marketing adjectives ("perfect for", "ideal", "beautiful"), no emoji.
What to exclude
- The requester's personal narrative. "I'm building a SvelteKit UI and need…" → drop the framing, keep the function.
- References to other issues, PRs, or icons by ID. No "As provided in #1865", "complementary to git-branch-plus", "same as above", "see #2055".
- Design/implementation chatter. Bezier offsets, grid alignment, path cuts, "the icon works perfectly" — none of that is a use-case.
- Restating the icon's name. For
microchip, "microchip" is not a use-case; describe what it represents ("Representing processors, chips, or embedded hardware"). - Links, image tags, emoji, and markdown artifacts.
- Meta-commentary. "Self-explanatory", "lots and lots of use cases", "obvious :)".
Cross-contamination
When a request covers several icons at once, assign each use-case only to the icon it actually describes. A bullet prefixed with another icon's name belongs to that icon, not this one. Don't let briefcase-medical's meanings leak into briefcase-business.
Variants
Related icons should get variant-specific wording, not one shared blurb. battery-low → "Indicating a low battery charge level"; battery-full → "…full…". square-arrow-right-enter → sign in / join; -exit → sign out / export. Resist copying the same line across a family.
Deriving from source material
When mining descriptions, comments, or linked issues:
- Prefer the stated purpose over the backstory. Extract the function, discard the anecdote.
- If a source lists genuinely distinct uses, keep them as separate entries; if it repeats one idea five ways, collapse to one.
- Merge an intro line with its bullets ("To represent:" + "pottery" → "Representing pottery").
- If the only signal is noise (a name restatement, a link, "thanks!"), leave the icon without a use-case rather than inventing one.
- Never fabricate a use-case that isn't supported by the icon's meaning or the source.
Examples
Good:
ambulance→ "Directing users to nearby emergency services in navigation apps"calendar-sync→ "Representing recurring events, promotions, or limited-time offers"globe-x→ "Indicating a device or application is offline or unreachable"heading-2→ "Applying a level-2 heading in text editors"
Poor → fixed:
"I need a firewall icon :-)"→ "Representing firewalls and firewall rules on cybersecurity platforms""As above"→ "Signifying a deal, agreement, or partnership""microchip"→ "Representing processors, chips, or embedded hardware""Same use cases as the other currency symbols, except Turkish lira"→ "Displaying prices or amounts in Turkish lira"