Mirrors/lucide
1
0
Fork 0
mirror of https://github.com/lucide-icons/lucide.git synced 2026-08-29 10:58:22 +02:00
Code Issues Packages Projects Releases Wiki Activity

feat(docs): update titles, split use case & tag guide

Browse Source
This commit is contained in:
Karsa
2026-08-25 11:37:18 +02:00
parent 640c3e0490
commit 04612398e7
12 changed files with 352 additions and 171 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/.vitepress/sidebar/resources.ts
View File

@@ -55,6 +55,18 @@ export const resourcesSidebar = [
text: 'Metadata conventions',
link: '/contribute/icons/metadata-conventions',
desc: 'Learn how to write tags, categories, aliases, and other metadata for Lucide icons.',
items: [
{
text: 'Use case guide',
link: '/contribute/icons/metadata-conventions/use-case-guide',
desc: '',
},
{
text: 'Tag guide',
link: '/contribute/icons/metadata-conventions/tag-guide',
desc: '',
},
],
},
{
text: 'SVG conventions',

8
docs/.vitepress/theme/style.css
View File

@@ -235,7 +235,7 @@ html {
.example-guidance__text {
display: flex;
flex-direction: row;
flex-direction: column;
gap: 8px;
align-items: center;
justify-content: center;
@@ -251,6 +251,12 @@ html {
text-align: center;
}
.example-guidance__text svg.lucide {
flex-shrink: 0;
display: inline-block;
vertical-align: -6px;
}
.example-guidance__caption {
color: var(--vp-c-text-1);
}

8
docs/contribute/icons/affinity-designer-guide.md
View File

@@ -1,14 +1,14 @@
---
title: Affinity Designer Template Guide
description: Learn how to use the Affinity Designer template for Lucide.
---
# Affinity Designer Template Guide
# Affinity Designer template guide
This guide describes how to use the Affinity Designer template for Lucide.
## General Workflow
## General workflow
>Attention: By default, Affinity Designer sets the unit for stroke to points. Make sure that it is set to pixel. To do this, open `Preferences > User Interface`. Under `Decimal Places for Unit Types`, uncheck `Show Lines in points`.
> Attention: By default, Affinity Designer sets the unit for stroke to points. Make sure that it is set to pixel. To do this, open `Preferences > User Interface`. Under `Decimal Places for Unit Types`, uncheck `Show Lines in points`.
1. Download and open the [Affinity Designer template](https://github.com/lucide-icons/lucide/blob/main/docs/public/templates/affinity_designer.aftemplate).
2. Follow the [Icon Design Principles](design-principles.md) while you use the template (to ensure integrity with the Lucide icon pack).

16
docs/contribute/icons/code-conventions.md
View File

@@ -1,8 +1,12 @@
## Code Conventions
---
description: Learn about allowed SVG elements and attributes, optimization, and other code conventions.
---
# SVG conventions
Before an icon is added to the library, we like to have readable and optimized SVG code.
### Global Attributes
## Global attributes
For each icon these attributes are applied, corresponding to the above rules.
@@ -22,12 +26,12 @@ For each icon these attributes are applied, corresponding to the above rules.
</svg>
```
### Minify paths
## Minify paths
The code of paths can sometimes get quite large. To reduce file size we like to minify the code.
We recommend to use [Lucide Studio](https://studio.lucide.dev/?utm_source=lucide.dev&utm_medium=design-guide) to tidy paths to 3 points of precision.
### Allowed elements
## Allowed elements
SVG files may only contain simple path and shape elements, which may not have any attributes other than sizing and spacing.\
In practice only the following elements and attributes are allowed:
@@ -81,5 +85,5 @@ Before opening a PR, confirm that:
- Only allowed SVG elements and attributes are used.
- The SVG does not use transforms, filters, fills, explicit strokes, or `<use>`.
- The icon has a matching JSON metadata file.
- `pnpm run lint:icons` passes.
- `pnpm run lint:json:icons` passes.
- Ensure that `pnpm run lint:icons` passes.
- Ensure that `pnpm run lint:json:icons` passes.

18
docs/contribute/icons/figma-guide.md
View File

@@ -1,12 +1,13 @@
---
title: Figma Template Guide
description: Learn how to use Figma for creating icons for Lucide.
---
# Figma Template Guide
# Figma template guide
This guide shows the steps to setup Figma for creating icons that conform to the Featherity design guidelines.
This guide shows the steps to set up Figma for creating icons that conform to the Lucide design guidelines.
## Setting up the frame
## Setting Up The Frame
When you create a new document in Figma, the document. Each individual icon you want to create, has to be created in a separate frame.
To do this, create a frame of 24x24 pixels.
@@ -16,7 +17,8 @@ To do this, create a frame of 24x24 pixels.
In this newly created frame, you will create your icon. If you want, you can change the name of your frame to the name of the icon you are going to create. Then it will be exported as `FRAME-NAME.svg`.
## Create Your icon
## Create your icon
To design your icon in the style of Feather Icons, you need to adjust a few settings in Figma.
Draw in your new frame with the pen tool. You can open it with the window at the top, or with the shortcut `P`. Once you click in your frame, you can adjust the settings for the pen tool in the design-window on the right.
@@ -30,7 +32,8 @@ Set the following:
![Figma Stroke Options](../../images/figma-stroke-options.png)
## Export Or Copy Your Icon
## Export or copy your icon
Once you have completed your icon, you can export it.
1. Select the frame
@@ -47,5 +50,6 @@ Or you can also copy its source as SVG.
That's it. You just made your first icon. Congratulations!
## Figma Tips
## Figma tip
1. The [Icon Design Guidelines](design-principles.md) dictate that you keep 2px spacing between detached elements. In Figma, you can easily check this with: `⌥` Option (MacOS) or `Alt` (Windows).

8
docs/contribute/icons/illustrator-guide.md
View File

@@ -1,14 +1,14 @@
---
title: Illustrator Template Guide
description: Learn how to properly use the Adobe Illustrator template for Lucide.
---
# Illustrator Template Guide
# Adobe Illustrator template guide
This Guide explains how to properly use the Adobe Illustrator Template for Lucide.
This guide explains how to properly use the Adobe Illustrator template for Lucide.
>Attention: Even though it is unlikely the template can be outdated or not 100% correct. Please check the Icon Design Guide before you start working with the template to ensure integrity with the Lucide icon pack.
## General Workflow
## General workflow
The Illustrator template is created following guidelines from the [Icon Design Guide](design-principles.md).

9
docs/contribute/icons/index.md
View File

@@ -1,11 +1,10 @@
---
title: Contributing Icons
description: Guidelines and instructions for contributing icons to Lucide.
description: Guidelines and instructions for contributing icons to Lucide
---
<script setup>
import OverviewLink from '../../.vitepress/theme/components/base/OverviewLink.vue'
import OverviewLinkGrid from '../../.vitepress/theme/components/base/OverviewLinkGrid.vue'
import { resourcesSidebar } from '../../.vitepress/sidebar/resources.ts'
import OverviewLink from '../../.vitepress/theme/components/base/OverviewLink.vue';
import OverviewLinkGrid from '../../.vitepress/theme/components/base/OverviewLinkGrid.vue';
import { resourcesSidebar } from '../../.vitepress/sidebar/resources.ts';
</script>
# Designing icons for Lucide

5
docs/contribute/icons/inkscape-guide.md
View File

@@ -1,11 +1,10 @@
---
title: Icon Design Guide
description: Learn how to set up Inkscape for creating icons for Lucide.
---
# Inkscape Setup Guide
This guide shows the steps to setup Inkscape for creating icons that conform to the Lucide design
guidelines.
This guide shows the steps to set up Inkscape for creating icons that conform to the Lucide design guidelines.
## Setting up The Canvas

159
docs/contribute/icons/metadata-conventions.md → docs/contribute/icons/metadata-conventions/index.md
View File

@@ -2,6 +2,11 @@
description: Learn how to write clear and consistent metadata for Lucide icons.
---
<script setup>
import OverviewLink from '../../../.vitepress/theme/components/base/OverviewLink.vue';
import OverviewLinkGrid from '../../../.vitepress/theme/components/base/OverviewLinkGrid.vue';
</script>
# Metadata conventions
Every Lucide icon has a matching JSON metadata file. Metadata helps credit contributors, categorize icons, improve search, and explain where an icon is useful.
@@ -54,12 +59,12 @@ A minimal metadata file looks like this:
## Contributors
The `contributors` field is a list of GitHub usernames for people who created or meaningfully contributed to the icon:
The `contributors` field is a list of GitHub usernames for people who created or meaningfully contributed to the icon.
### Contributor rules
1. If you create a new icon based on existing ones, add all contributors from all base icons.
2. Add a username when someone made a significant contribution to the SVG itself.
3. Do not add people for minor review comments, metadata-only edits, or unrelated discussion.
## Use cases
@@ -72,142 +77,22 @@ Use cases should be short phrases, not full sentences. Start with a present part
- Indicating...
- Marking...
- Showing...
- Confirming...
- Toggling...
- Categorizing...
- Searching...
Keep each use case focused on one idea. Prefer 1 to 4 strong use cases over a long list of weak or repetitive ones.
### Use case rules
### Write from the interface's perspective
- Keep each use case focused on one idea
- Keep entries concise and specific
- Write from the interface's perspective
- Describe real usage, not the icon name or appearance
- Add context when it clarifies meaning
- Do not end with punctuation
- Do not add markdown and emoji
- Do not add implementation details or PR references
Describe what the interface communicates to the user. Do not write from the contributor's personal point of view.
:::: example
::: do Indicating a device is offline or unreachable
This describes the role the icon plays in an interface.
:::
::: dont I need an icon for my offline device screen
This explains the contributor's situation, not the icon's reusable purpose.
:::
::::
### Describe real usage, not the icon name
A use case should explain what the icon means in context. Do not repeat the icon name or describe only the drawing.
:::: example
::: do Representing processors, chips, or embedded hardware
This makes `microchip` useful in search and documentation without restating the name.
:::
::: dont it's a microchip icon
This duplicates the icon name and does not explain where the icon would be used.
:::
::::
### Add context when it clarifies meaning
Some icons have broad meanings. Add a short context when it makes the use case easier to understand.
:::: example
::: do Applying a level-2 heading in text editors
The phrase explains both the action and the product area.
:::
::: dont Applying a heading
This is understandable, but less useful because it omits the level and interface context.
:::
::::
### Keep each use case focused
Each entry should contain one clear idea. Split genuinely different meanings into separate entries.
:::: example
::: do Marking parking locations on maps
This is short, concrete, and focused on one interface function.
:::
::: dont Marking parking, transport, maps, cars, garages, and places
This reads like a tag list and mixes several concepts into one use case.
:::
::::
### Write variant-specific use cases
Related icons should describe what makes each variant different.
:::: example
::: do Indicating a low battery charge level
This is specific to `battery-low` and distinguishes it from other battery icons.
:::
::: dont Representing battery status
This is too generic and could apply to every battery variant.
:::
::::
### Avoid references that only make sense in a PR
Use cases should stand on their own after the PR is merged.
:::: example
::: do Signifying a deal, agreement, or partnership
This preserves the useful meaning without depending on outside context.
:::
::: dont Same as above in #1234
This depends on a discussion that readers may never see.
:::
::::
### Keep entries concise
Use cases should usually be 4 to 12 words. Prefer one strong phrase over a long explanation.
:::: example
::: do Searching files by name or content
This is short enough to scan and specific enough to understand.
:::
::: dont This icon can be used when users want to search through all of their files and folders to find something
This is too long and reads like product copy instead of metadata.
:::
::::
### Do not end with punctuation
Use cases are metadata phrases, not full sentences.
:::: example
::: do Confirming a successful payment
This matches the phrase style used across icon metadata.
:::
::: dont Confirming a successful payment.
The period adds unnecessary punctuation and makes entries inconsistent.
:::
::::
### Avoid markdown and emoji
Use plain text only. Formatting belongs in documentation, not metadata values.
:::: example
::: do Warning users about a destructive action
This works in search, generated pages, and other metadata consumers.
:::
::: dont <span>**Warning** users about a destructive action ⚠️</span>
Markdown and emoji can leak into generated UI and make metadata harder to reuse.
:::
::::
### Avoid implementation details
Use cases should describe meaning, not how the SVG was built.
:::: example
::: do Representing cropped or trimmed content
This explains the icon's interface meaning.
:::
::: dont Showing a rectangle with two path cuts and adjusted Bezier handles
This describes construction details that do not help users find or understand the icon.
:::
::::
<OverviewLinkGrid>
<OverviewLink href="./use-case-guide.md" title="Use case guide" desc="Learn the best practices for writing use cases"/>
</OverviewLinkGrid>
## Tags
@@ -228,6 +113,10 @@ Use existing tags in the repository as a reference before adding new ones. This
For example, a `mail-search` icon can use tags such as `email`, `message`, `letter`, `find`, and `filter`, but it should not include `mail-search` as a tag.
<OverviewLinkGrid>
<OverviewLink href="./tag-guide.md" title="Tag guide" desc="Learn the best practices for writing tags"/>
</OverviewLinkGrid>
## Categories
The `categories` field groups icons into broad areas of use.

131
docs/contribute/icons/metadata-conventions/tag-guide.md Normal file
View File

@@ -0,0 +1,131 @@
---
description: Learn the best practices for writing tags for Lucide icons.
---
<script setup>
import { batteryLow, calendar, droplet, hospital, mail, mailSearch, search, type } from '~/.vitepress/data/iconNodes';
import LucideIcon from '~/.vitepress/theme/components/base/LucideIcon.vue';
</script>
# Tag guide
This guide will teach you how to write useful search tags for Lucide icons.
Tags help people find icons when they search for related concepts, synonyms, contexts, or common alternate wording.
## Use lowercase tags
Tags should always be lowercase so search metadata stays consistent.
:::: example
::: do <LucideIcon :iconNode="mail" /> email
Lowercase tags **match the style** used across the icon library.
:::
::: dont <LucideIcon :iconNode="mail" /> Email
Capitalized tags create **inconsistent metadata** without improving search.
:::
::::
## Prefer short tags
Use one clear word when it carries the meaning. Multi-word tags are fine when they are the clearest search term.
:::: example
::: do <LucideIcon :iconNode="search" /> search
This is **short, common, and easy to match** in search.
:::
::: dont <LucideIcon :iconNode="search" /> searching through files & folders
This reads like a **use case**, not a tag.
:::
::::
## Use multi-word tags when needed
Some concepts are only clear as a phrase. Keep those phrases concise.
:::: example
::: do <LucideIcon :iconNode="droplet" /> blood type
The phrase is **clearer** than either word on its own.
:::
::: dont <LucideIcon :iconNode="droplet" /> blood type medical label
This combines **several search concepts** into one long tag.
:::
::::
## Add synonyms and common wording
Tags can include words people are likely to search for, even when they are not the icon's exact name.
:::: example
::: do <LucideIcon :iconNode="mail" /> email
This helps users find `mail` icons using a **common synonym**.
:::
::: dont <LucideIcon :iconNode="mail" /> electronic postal message delivery
This is unlikely search wording and **adds noise**.
:::
::::
## Do not repeat the icon name
The icon name is already searchable. Tags should add new ways to find the icon.
:::: example
::: do <LucideIcon :iconNode="mailSearch" /> message filter
This adds a **related concept** for `mail-search` without duplicating the name.
:::
::: dont <LucideIcon :iconNode="mailSearch" /> mail search
This **repeats the icon name** and does not improve discovery.
:::
::::
## Avoid generic tags
Tags should describe the icon, not the fact that it is an icon.
:::: example
::: do <LucideIcon :iconNode="calendar" /> event
This points to a **concrete concept** users might search for.
:::
::: dont <LucideIcon :iconNode="calendar" /> icon
**Every entry is an icon**, so this tag does not help anyone find the right one.
:::
::::
## Keep tags relevant
Do not add loosely related terms just to make an icon appear in more searches.
:::: example
::: do <LucideIcon :iconNode="hospital" /> emergency room
This is **relevant** for an icon that marks ER locations.
:::
::: dont <LucideIcon :iconNode="hospital" /> doctor nurse pharmacy
These terms may be **nearby concepts**, but they do not all describe the same icon.
:::
::::
## Match the specific variant
Related icons should share useful family terms, but variant tags should describe what is different.
:::: example
::: do <LucideIcon :iconNode="batteryLow" /> depleted
This distinguishes `battery-low` from **other battery icons**.
:::
::: dont <LucideIcon :iconNode="batteryLow" /> charged
This **better describes** `battery-full`, not `battery-low`.
:::
::::
## Use existing tags as a reference
Check similar icons before inventing new tags. Reusing established terms keeps search behavior predictable.
:::: example
::: do <LucideIcon :iconNode="type" /> typography
This matches existing text-formatting icons and keeps **related icons** grouped in search.
:::
::: dont <LucideIcon :iconNode="type" /> fontography
Inventing a new term makes the icon harder to find and **less consistent** with nearby metadata.
:::
::::

137
docs/contribute/icons/metadata-conventions/use-case-guide.md Normal file
View File

@@ -0,0 +1,137 @@
---
description: Learn the best practices for writing use cases for Lucide icons.
---
# Use case guide
This guide will teach you how to write the best use cases for Lucide icons.
## Write from the interface's perspective
Describe what the interface communicates to the user. Do not write from the contributor's personal point of view.
:::: example
::: do Indicating a device is offline or unreachable
This describes the **role the icon plays in an interface**.
:::
::: dont I need an icon for my offline device screen
This explains the **contributor's situation**, not the icon's reusable purpose.
:::
::::
## Describe real usage, not the icon name
A use case should explain what the icon means in context. Do not repeat the icon name or describe only the drawing.
:::: example
::: do Representing processors, chips, or embedded hardware
This makes `microchip` useful in search and documentation **without restating the name**.
:::
::: dont it's a microchip icon
This **duplicates the icon name** and does not explain where the icon would be used.
:::
::::
## Add context when it clarifies meaning
Some icons have broad meanings. Add a short context when it makes the use case easier to understand.
:::: example
::: do Applying a level-2 heading in text editors
The phrase explains both the **action and the product area**.
:::
::: dont Applying a heading
This is understandable, but less useful because it **omits the level and interface context**.
:::
::::
## Keep each use case focused
Each entry should contain one clear idea. Split genuinely different meanings into separate entries.
:::: example
::: do Marking parking locations on maps
This is **short, concrete, and focused** on one interface function.
:::
::: dont Marking parking, transport, maps, cars, garages, and places
This reads like a **tag list** and **mixes several concepts** into one use case.
:::
::::
## Write variant-specific use cases
Related icons should describe what makes each variant different.
:::: example
::: do Indicating a low battery charge level
This is specific to `battery-low` and **distinguishes** it from other battery icons.
:::
::: dont Representing battery status
This is **too generic** and could apply to **every battery variant**.
:::
::::
## Avoid references that only make sense in a PR
Use cases should stand on their own after the PR is merged.
:::: example
::: do Signifying a deal, agreement, or partnership
This preserves the **useful meaning** without depending on **outside context**.
:::
::: dont Same as above in #1234
This **depends on a discussion** that readers **may never see**.
:::
::::
## Keep entries concise
Use cases should usually be 4 to 12 words. Prefer one strong phrase over a long explanation.
:::: example
::: do Searching files by name or content
This is **short enough** to scan and **specific enough** to understand.
:::
::: dont This icon can be used when users want to search through all of their files and folders to find something
This is **too long** and reads like **product copy instead of metadata**.
:::
::::
## Do not end with punctuation
Use cases are metadata phrases, not full sentences.
:::: example
::: do Confirming a successful payment
This matches the **phrase style** used across icon metadata.
:::
::: dont Confirming a successful payment.
The period adds **unnecessary punctuation** and makes entries inconsistent.
:::
::::
## Avoid markdown and emoji
Use plain text only. Formatting belongs in documentation, not metadata values.
:::: example
::: do Warning users about a destructive action
This works in search, generated pages, and other **metadata consumers**.
:::
::: dont <span>**Warning** users about a destructive action ⚠️</span>
Markdown and emoji can **leak into generated UI** and make metadata **harder to reuse**.
:::
::::
## Avoid implementation details
Use cases should describe meaning, not how the SVG was built.
:::: example
::: do Representing cropped or trimmed content
This explains the icon's **interface meaning**.
:::
::: dont Showing a rectangle with two path cuts and adjusted Bezier handles
This describes **construction details** that do not help users find or understand the icon.
:::
::::

12
docs/contribute/icons/naming-conventions.md
View File

@@ -2,7 +2,7 @@
description: Learn how to choose clear and consistent names for Lucide icons.
---
<script setup>
import { arrowDown01, sendHorizontal, heartCrack, circleDashed, circleUser, clock3, userRound, save, ban, pencilRuler } from '~/.vitepress/data/iconNodes';
import { arrowDown01, badgePlus, badgeCheck, sendHorizontal, heartCrack, circleDashed, circleUser, clock3, userRound, save, ban, pencilRuler } from '~/.vitepress/data/iconNodes';
import LucideIcon from '~/.vitepress/theme/components/base/LucideIcon.vue';
const pencilRulerHorizontal = [
["path",{"d":"M10 16v-3","key":"1sz6hv"}],
@@ -50,9 +50,9 @@ Avoid other naming schemes.
Icon names **must** use American English names, as opposed to local variants.
:::: example
::: do `color`, `maximize`, `center`
::: do <span>`color`, `maximize`, `center`</span>
:::
::: dont `colour`, `maximise`, `centre`
::: dont <span>`colour`, `maximise`, `centre`</span>
:::
::::
@@ -89,10 +89,10 @@ Icons that belong to the same group **must** use the `<group>-<variant>` naming
The group name comes first, followed by the part that distinguishes the icon from the rest of the group.
:::: example
::: do `badge-plus` & `badge-check`
::: do <span><LucideIcon :iconNode="badgePlus" /> + <LucideIcon :iconNode="badgeCheck" /></span> <span>`badge-plus` & `badge-check`</span>
`badge` is the group.
:::
::: dont `plus-badge` & `check-badge`
::: dont <span><LucideIcon :iconNode="badgePlus" /> + <LucideIcon :iconNode="badgeCheck" /></span> <span>`plus-badge` & `check-badge`</span>
`plus` and `check` are not the group.
:::
::::
@@ -105,7 +105,7 @@ Alternate versions of an icon **must** be named for what makes them visually dis
::: do <LucideIcon :iconNode="sendHorizontal" /> `send-horizontal`
The icon depicts a horizontal "send" symbol.
:::
::: dont <LucideIcon :iconNode="sendHorizontal" /> `send-2` or `send-alt`
::: dont <LucideIcon :iconNode="sendHorizontal" /> <span>`send-2` or `send-alt`</span>
"send no. 2" or "alternative send" are not descriptive names.
:::
::::