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

docs/.vitepress/sidebar/resources.ts

@@ -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',

docs/.vitepress/theme/style.css

@@ -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);
 }

docs/contribute/icons/affinity-designer-guide.md

@@ -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).

docs/contribute/icons/code-conventions.md

@@ -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.
+- Ensure that `pnpm run lint:icons` passes.
-- `pnpm run lint:json:icons` passes.
+- Ensure that `pnpm run lint:json:icons` passes.

docs/contribute/icons/figma-guide.md

@@ -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).

docs/contribute/icons/illustrator-guide.md

@@ -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).
 

docs/contribute/icons/index.md

@@ -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 OverviewLink from '../../.vitepress/theme/components/base/OverviewLink.vue';
-import OverviewLinkGrid from '../../.vitepress/theme/components/base/OverviewLinkGrid.vue'
+import OverviewLinkGrid from '../../.vitepress/theme/components/base/OverviewLinkGrid.vue';
-import { resourcesSidebar } from '../../.vitepress/sidebar/resources.ts'
+import { resourcesSidebar } from '../../.vitepress/sidebar/resources.ts';
 </script>
 
 # Designing icons for Lucide

docs/contribute/icons/inkscape-guide.md

@@ -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
+This guide shows the steps to set up Inkscape for creating icons that conform to the Lucide design guidelines.
-guidelines.
 
 ## Setting up The Canvas
 

docs/contribute/icons/metadata-conventions/index.md

@@ -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.
+<OverviewLinkGrid>
-
+  <OverviewLink href="./use-case-guide.md" title="Use case guide" desc="Learn the best practices for writing use cases"/>
-:::: example
+</OverviewLinkGrid>
-::: 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.
-:::
-::::
 
 ## 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.

docs/contribute/icons/metadata-conventions/tag-guide.md

@@ -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.
+:::
+::::

docs/contribute/icons/metadata-conventions/use-case-guide.md

@@ -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.
+:::
+::::

docs/contribute/icons/naming-conventions.md

@@ -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.
 :::
 ::::