feat(docs): added ux writing instructions & proofread markdowns to match these guidelines

2026-08-29 12:18:23 +02:00 · 2026-08-25 17:34:28 +02:00
parent 1b0a098c2a
commit dc8b2b90cc
14 changed files with 887 additions and 311 deletions
--- a/.github/instructions/ux-writing.instructions.md
+++ b/.github/instructions/ux-writing.instructions.md
@@ -0,0 +1,587 @@
+---
+applyTo: "docs/*.md"
+---
+# UX writing guidelines
+
+Follow these guidelines when writing or editing Lucide documentation, especially Markdown files.
+
+Write for people who are trying to understand a concept, follow a specification, or complete a task. Prioritize clarity, precision, and scannability over personality or decorative prose.
+
+## Be direct and concise
+
+State the important information first. Remove words that do not add meaning.
+
+Prefer short sentences and paragraphs, but do not sacrifice precision just to make text shorter.
+
+**Do:**
+
+> Icons must use a 24 × 24 pixel canvas.
+
+**Don't:**
+
+> When creating a new icon, you should make sure that the canvas you're working with has dimensions of 24 × 24 pixels.
+
+Avoid unnecessary introductions such as:
+
+- "It's important to note that…"
+- "Keep in mind that…"
+- "As you can see…"
+- "In order to…"
+- "It should be noted that…"
+
+State the information directly instead.
+
+## Put the rule before the explanation
+
+When documenting a requirement or recommendation, state it before explaining why it exists.
+
+**Do:**
+
+> Keep at least 1 pixel of space between unrelated elements. This prevents shapes from visually merging at small sizes.
+
+**Don't:**
+
+> Because shapes can visually merge at small sizes, it's important to make sure that unrelated elements have enough space between them.
+
+This makes documentation easier to scan and makes normative requirements easier to identify.
+
+## Explain the reason when it adds value
+
+Explain *why* a rule exists when the reasoning helps contributors apply it to situations that are not explicitly documented.
+
+Do not merely restate the rule.
+
+**Do:**
+
+> Avoid simulated fills. They don't scale consistently with the rest of the icon set.
+
+**Don't:**
+
+> Avoid simulated fills because simulated fills should not be used.
+
+Reasoning is particularly useful for design rules where contributors may need to evaluate unusual cases.
+
+## Use scannable structure
+
+Assume readers will scan the page before reading it in detail.
+
+Use:
+
+- descriptive headings
+- short paragraphs
+- lists for sets of related items
+- examples for rules that benefit from demonstration
+- **bold** for important terms or short emphasis
+- code formatting for filenames, properties, commands, values, and identifiers
+
+Avoid long uninterrupted blocks of text.
+
+Headings should communicate the subject or rule without requiring the surrounding text for context.
+
+**Do:**
+
+> ## Keep 1 pixel of safe space
+
+**Don't:**
+
+> ## Spacing
+
+## Use sentence case
+
+Use sentence case for:
+
+- page titles
+- headings
+- table headings
+- labels
+- example captions
+
+Capitalize proper nouns and branded terms normally.
+
+**Do:**
+
+> ## Use consistent corner radii
+
+**Don't:**
+
+> ## Use Consistent Corner Radii
+
+## Address the reader directly
+
+Use **you** and **your** when referring to something the reader does.
+
+**Do:**
+
+> If your icon contains overlapping shapes, simplify the hidden geometry.
+
+Avoid referring to the reader as "the user," "the contributor," or other third-person terms when direct language is more natural.
+
+However, prefer an imperative when the subject is obvious.
+
+**Prefer:**
+
+> Keep related elements visually grouped.
+
+**Over:**
+
+> You should keep related elements visually grouped.
+
+## Use "we" only when it means the Lucide project or maintainers
+
+First-person plural is acceptable when describing an intentional project decision, convention, or policy.
+
+**Do:**
+
+> We use `kebab-case` for icon names.
+
+> We generally avoid adding brand logos to Lucide.
+
+Do not use "we" merely to make documentation conversational.
+
+**Prefer:**
+
+> Icons use a 2 pixel stroke.
+
+**Over:**
+
+> We use a 2 pixel stroke for our icons.
+
+## Use normative language consistently
+
+Use specific language to communicate how strictly a rule applies.
+
+- **must** — required; violating this is not acceptable
+- **must not** — prohibited
+- **should** — recommended; exceptions may be appropriate
+- **should not** — discouraged; exceptions may be appropriate
+- **can** — possible or permitted
+- **may** — optional or dependent on context
+
+Do not use **should** when something is actually required.
+
+**Do:**
+
+> Icons must use a 24 × 24 pixel canvas.
+
+**Don't:**
+
+> Icons should use a 24 × 24 pixel canvas.
+
+Avoid vague substitutes such as "ideally," "normally," or "preferably" when a more precise normative term applies.
+
+## Prefer active voice
+
+Use active voice unless passive voice makes the subject clearer or avoids unnecessary repetition.
+
+**Do:**
+
+> Align nodes to the pixel grid.
+
+**Don't:**
+
+> Nodes should be aligned to the pixel grid.
+
+Passive voice is acceptable when the actor is irrelevant.
+
+> Deprecated icons are removed in major releases.
+
+## Use positive instructions when possible
+
+Tell readers what to do rather than only what not to do.
+
+**Do:**
+
+> Use a single continuous path when the elements form one continuous shape.
+
+**Less useful:**
+
+> Don't split continuous shapes into unnecessary paths.
+
+Use negative instructions when the prohibition itself is important.
+
+> Don't use simulated fills.
+
+## Be precise about consequences
+
+When explaining why something should or should not be done, describe the actual consequence rather than using vague warnings.
+
+**Do:**
+
+> Keep unrelated elements at least 2 pixels apart. Smaller gaps can disappear when the icon is rendered at small sizes.
+
+**Don't:**
+
+> Be careful when placing elements too close together.
+
+Avoid language that exaggerates consequences or attempts to influence a contributor's decision emotionally.
+
+## Prefer concrete language
+
+Use specific terms instead of vague references.
+
+**Do:**
+
+> The two endpoints must remain inside the 1 pixel safe zone.
+
+**Don't:**
+
+> These should stay within the appropriate area.
+
+Avoid ambiguous references such as:
+
+- this
+- that
+- it
+- things
+- stuff
+- appropriate
+- proper
+- correct
+
+when the intended subject can be named directly.
+
+## Introduce terminology before relying on it
+
+Define Lucide-specific or technical terms when readers may not already know them.
+
+Once defined, use the same term consistently.
+
+**Do:**
+
+> The **safe zone** is the 1 pixel area between the icon artwork and the canvas boundary.
+
+Do not alternate between different terms for the same concept unless the distinction is intentional.
+
+For example, don't alternate between "safe zone," "padding," and "margin" if they refer to the same rule.
+
+## Use abbreviations sparingly
+
+Spell out uncommon abbreviations on first use.
+
+> Scalable Vector Graphics (SVG)
+
+Common technical abbreviations such as HTML, CSS, SVG, API, and URL do not need to be expanded when the intended audience can reasonably be expected to know them.
+
+Avoid Latin abbreviations such as:
+
+- e.g.
+- i.e.
+- etc.
+
+Prefer:
+
+- for example
+- that is
+- and so on
+
+## Use examples deliberately
+
+Use examples when they clarify how to apply a rule.
+
+Keep examples focused on the rule being demonstrated. Avoid introducing unrelated differences that make the comparison harder to understand.
+
+When contrasting examples, use **Do** and **Don't** consistently.
+
+**Do:**
+
+> Use one path for a continuous outline.
+
+**Don't:**
+
+> Split a continuous outline into several overlapping paths.
+
+The explanatory text should describe the principle, not merely narrate what is visible in the example.
+
+## Use links descriptively
+
+Link text should describe the destination or concept.
+
+**Do:**
+
+> See the [Icon Design Specification](./specification) for exact dimensions and spacing requirements.
+
+**Don't:**
+
+> For more information, [click here](./specification).
+
+Avoid generic link text such as:
+
+- click here
+- here
+- this page
+- learn more
+
+when a descriptive label is possible.
+
+## Avoid unnecessary repetition
+
+Do not repeat information already established by a heading, example, or immediately preceding sentence.
+
+**Prefer:**
+
+> ## Keep 1 pixel of safe space
+>
+> Keep all artwork within the 22 × 22 pixel live area.
+
+**Over:**
+
+> ## Keep 1 pixel of safe space
+>
+> When designing an icon, you should keep 1 pixel of safe space around the icon.
+
+Cross-reference another section instead of duplicating detailed rules that already have a canonical explanation.
+
+## Use contractions in prose
+
+Use natural contractions such as:
+
+- don't
+- can't
+- isn't
+- it's
+- you'll
+
+They make explanatory prose less formal and easier to scan.
+
+Use uncontracted forms when deliberate emphasis is useful.
+
+> Do not change existing icon geometry solely to reduce the number of SVG nodes.
+
+Normative statements using **must not** should not be contracted.
+
+## Use the serial comma
+
+Use the serial (Oxford) comma in lists of three or more items.
+
+**Do:**
+
+> Check the icon's size, stroke width, and spacing.
+
+**Don't:**
+
+> Check the icon's size, stroke width and spacing.
+
+## Use punctuation normally in prose
+
+Use periods for complete sentences.
+
+Periods may be omitted from:
+
+- headings
+- short labels
+- short list items that are not complete sentences
+- captions consisting only of a short phrase
+
+Be consistent within a list.
+
+If list items are complete sentences, end them with periods. If they are fragments, generally omit periods.
+
+## Skip colons in headings
+
+Do not end headings with colons.
+
+**Do:**
+
+> ## Naming conventions
+
+**Don't:**
+
+> ## Naming conventions:
+
+Use a colon normally when introducing a list or explanation in body text.
+
+## Use exclamation points sparingly
+
+Avoid exclamation points in technical documentation unless the context genuinely calls for excitement or celebration.
+
+**Prefer:**
+
+> Your first icon is ready.
+
+**Over:**
+
+> Your first icon is ready!
+
+Do not use exclamation points to make instructions sound friendlier.
+
+## Use ellipses only when they have meaning
+
+Use an ellipsis (`…`) to represent omitted content or an intentionally incomplete statement.
+
+Do not use ellipses decoratively or to make prose sound conversational.
+
+When documenting literal UI text, preserve the punctuation used by the interface.
+
+## Use parentheses for definitions and compact clarification
+
+Use parentheses when they make a definition, abbreviation, or short clarification easier to understand.
+
+> Scalable Vector Graphics (SVG)
+
+Avoid using parentheses for long side notes. Rewrite important information as part of the sentence or as a separate sentence.
+
+## Prefer "and" over ampersands
+
+Use **and** in normal prose.
+
+**Do:**
+
+> Naming and metadata
+
+**Avoid:**
+
+> Naming & metadata
+
+Use an ampersand only when it is part of an official name, literal UI text, code, or another established term.
+
+## Avoid em dashes
+
+Prefer commas, periods, colons, or parentheses when they produce a simpler sentence.
+
+**Prefer:**
+
+> This rule has one exception: existing legacy icons.
+
+**Avoid:**
+
+> This rule has one exception — existing legacy icons.
+
+Use an en dash (`–`) without surrounding spaces for ranges.
+
+> 1–3 pixels
+
+> A–Z
+
+Do not substitute a hyphen for an en dash in prose ranges unless required by a technical syntax.
+
+## Use hyphens correctly
+
+Hyphenate compound modifiers when necessary for clarity.
+
+> 24 × 24 pixel canvas
+
+> 2-pixel-wide gap
+
+> pixel-aligned element
+
+Do not hyphenate a phrase when it functions as a verb.
+
+> Sign off on the design.
+
+> Complete the sign-off.
+
+Do not add hyphens mechanically when the meaning is already clear.
+
+## Use code formatting consistently
+
+Use backticks for literal technical values and identifiers, including:
+
+- filenames and paths
+- commands
+- package names
+- properties and attributes
+- icon names
+- code values
+- SVG elements and attributes
+
+**Do:**
+
+> Add `camera-off` as an alias.
+
+> Set `stroke-width` to `2`.
+
+> Edit `icons/camera.svg`.
+
+Do not use code formatting merely for emphasis.
+
+## Use bold for semantic emphasis
+
+Use **bold** sparingly to highlight a term or distinction that helps readers scan the page.
+
+Do not bold entire sentences or paragraphs.
+
+Prefer bold over italics for general emphasis.
+
+Use *italics* only when conventional, such as when referring to a term as a term or when a specific distinction benefits from it.
+
+## Don't use all caps for emphasis
+
+Do not use blocks of uppercase text for emphasis.
+
+**Don't:**
+
+> NEVER place nodes outside the canvas.
+
+**Do:**
+
+> **Never** place nodes outside the canvas.
+
+Preserve capitalization when documenting literal identifiers or established technical terms.
+
+## Keep lists parallel
+
+Items in the same list should use the same grammatical structure.
+
+**Do:**
+
+- Use a 24 × 24 pixel canvas
+- Keep 1 pixel of safe space
+- Use a 2 pixel stroke
+- Align nodes to the pixel grid
+
+**Don't:**
+
+- Use a 24 × 24 pixel canvas
+- Safe space should be 1 pixel
+- A 2 pixel stroke
+- Nodes are aligned to the pixel grid
+
+Parallel structure makes rules easier to scan and compare.
+
+## Avoid unnecessary filler and enthusiasm
+
+Lucide documentation should sound helpful and confident, not promotional.
+
+Avoid filler such as:
+
+- "Simply…"
+- "Just…"
+- "Obviously…"
+- "Of course…"
+- "Easy…"
+- "Luckily…"
+- "Don't worry…"
+
+These words can be inaccurate or dismissive when the task is not simple for the reader.
+
+Also avoid marketing language such as:
+
+- "powerful"
+- "seamless"
+- "effortless"
+- "amazing"
+- "best-in-class"
+
+unless the word communicates a specific, verifiable distinction.
+
+## Prefer timeless documentation
+
+Avoid wording tied unnecessarily to the current state of development.
+
+**Prefer:**
+
+> Lucide supports custom icon aliases.
+
+**Avoid:**
+
+> Lucide now supports custom icon aliases.
+
+Use time-sensitive language only when the timing itself matters, such as migration notes, deprecations, or release documentation.
+
+## Preserve established Lucide terminology
+
+When editing existing documentation, preserve established Lucide terminology and naming conventions unless there is a clear reason to change them.
+
+Do not invent synonyms merely to avoid repetition. Consistency is more important than stylistic variety in technical documentation.
+
+When terminology differs between the Lucide codebase, API, UI, and documentation, prefer the term used by the relevant canonical specification.
--- a/docs/.vitepress/sidebar/resources.ts
+++ b/docs/.vitepress/sidebar/resources.ts
@@ -11,7 +11,7 @@ export const resourcesSidebar = [
        link: '/community',
      },
      {
-        text: 'Code of Conduct',
+        text: 'Code of conduct',
        link: '/code-of-conduct',
      },
      {
@@ -37,14 +37,14 @@ export const resourcesSidebar = [
        link: '/contribute/icons/',
      },
      {
-        text: 'Design Language',
+        text: 'Design language',
        link: '/contribute/icons/design-principles',
-        desc: 'Learn the visual principles that make Lucide icons consistent and recognizable.',
+        desc: 'Learn the visual rules that make Lucide icons consistent and recognizable.',
      },
      {
-        text: 'Design Specification',
+        text: 'Design specification',
        link: '/contribute/icons/specification',
-        desc: 'Reference the concrete requirements that Lucide icons must or should follow.',
+        desc: 'Review the rules Lucide icons must follow.',
      },
      {
        text: 'Naming conventions',
@@ -54,7 +54,7 @@ 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.',
+        desc: 'Learn how to write use cases, tags, categories, aliases, and other icon metadata.',
        items: [
          {
            text: 'Use case guide',
@@ -71,12 +71,12 @@ export const resourcesSidebar = [
      {
        text: 'SVG conventions',
        link: '/contribute/icons/code-conventions',
-        desc: 'Learn how SVG files should be structured and written for the Lucide repository.',
+        desc: 'Learn how to structure and write Lucide SVG files.',
      },
      {
        text: 'Design software guides',
        collapsed: false,
-        desc: 'Learn how to design and export Lucide icons using common vector design tools.',
+        desc: 'Learn how to design and export Lucide icons with common vector tools.',
        items: [
          {
            text: 'Adobe Illustrator',
--- a/docs/contribute/icons/affinity-designer-guide.md
+++ b/docs/contribute/icons/affinity-designer-guide.md
@@ -4,15 +4,16 @@ description: Learn how to use the Affinity Designer template for Lucide.

 # Affinity Designer template guide

-This guide describes how to use the Affinity Designer template for Lucide.
+This guide explains how to use the Affinity Designer template for Lucide.

-## General workflow
+## 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`.
+> Affinity Designer uses points for strokes by default. Change strokes to pixels before drawing. Open `Preferences > User Interface`, then 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).
-3. Export the file as SVG (`File > Export`). Make sure that _Rastering_ is set to _Nothing_, _Export text as curves_ is checked (hopefully, you won't need this), _Use hex colors_ is checked, and _Flatten transforms_ is checked.
+2. Follow the [design language](design-principles.md) while designing your icon.
+3. Export the file as SVG with `File > Export`. Set rasterization to _Nothing_, check _Export text as curves_, check _Use hex colors_, and check _Flatten transforms_.

   ![SVG export options in Affinity Designer](../../images/affinity-designer-export-options.png?raw=true)
-4. Optimize the exported SVG file further with [SVGOMG](https://jakearchibald.github.io/svgomg/) or [`svgo`](https://github.com/svg/svgo) (using `svgo --multipass exported_icon.svg`).
+
+4. Optimize the exported SVG with [Lucide Studio](https://studio.lucide.dev/).
--- a/docs/contribute/icons/code-conventions.md
+++ b/docs/contribute/icons/code-conventions.md
@@ -4,11 +4,11 @@ description: Learn about allowed SVG elements and attributes, optimization, and

 # SVG conventions

-Before an icon is added to the library, we like to have readable and optimized SVG code.
+Before you add an icon to Lucide, make sure its SVG is readable and optimized.

 ## Global attributes

-For each icon these attributes are applied, corresponding to the above rules.
+Each icon uses these root SVG attributes:

 ```xml
 <svg
@@ -28,13 +28,15 @@ For each icon these attributes are applied, corresponding to the above rules.

 ## 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.
+Path data can get large. Minify it to keep SVG files small.
+
+Use [Lucide Studio](https://studio.lucide.dev/?utm_source=lucide.dev&utm_medium=design-guide) to tidy paths to 3 decimal places.

 ## 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:
+SVG files may only contain simple path and shape elements. These elements may only use sizing and position attributes.
+
+Only these elements and attributes are allowed:

 - `<path d>`
 - `<line x1 x2>`
@@ -44,15 +46,15 @@ In practice only the following elements and attributes are allowed:
 - `<ellipse cx cy rx ry>`
 - `<rect x y width height rx>`

-This also means that no transforms, filters, fills or explicit strokes are allowed.
+Do not use transforms, filters, fills, or explicit stroke colors.

-Never use [`<use>`](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/use). While it may sometimes seem like a good way to optimize file size, there's no way to ensure that the referenced element IDs will be unique once the SVGs are embedded in HTML documents.
+Never use [`<use>`](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/use). It can reduce file size, but referenced IDs may conflict when SVGs are embedded in HTML.

-## JSON metadata descriptor
+## Metadata file

-Each icon added must also come with a matching JSON file listing contributors, use cases, tags and categories for the icon.
+Each icon must also have a matching JSON file with contributors, use cases, tags, and categories.

-Please use consult [our metadata conventions page](./metadata-conventions.md) for more information about this file.
+See [metadata conventions](./metadata-conventions/) for details.

 ## Validation

@@ -76,14 +78,14 @@ pnpm run lint:icons:all

 ## Checklist

-Before opening a PR, confirm that:
+Before opening a pull request, confirm that:

- The SVG uses the standard `24` by `24` viewBox.
+- The SVG uses the standard `24 × 24` viewBox.
 - The SVG uses `fill="none"` and `stroke="currentColor"`.
 - Stroke width, line caps, and line joins match the Lucide defaults.
 - Paths are tidy and use appropriate numeric precision.
- Only allowed SVG elements and attributes are used.
+- The SVG uses only allowed elements and attributes.
 - The SVG does not use transforms, filters, fills, explicit strokes, or `<use>`.
 - The icon has a matching JSON metadata file.
- Ensure that `pnpm run lint:icons` passes.
- Ensure that `pnpm run lint:json:icons` passes.
+- `pnpm run lint:icons` passes.
+- `pnpm run lint:json:icons` passes.
--- a/docs/contribute/icons/design-principles.md
+++ b/docs/contribute/icons/design-principles.md
@@ -2,30 +2,28 @@
 description: Learn the visual principles that make Lucide icons consistent and recognizable.
 ---

-# Lucide Design Language
+# Lucide design language

-Lucide is designed as a consistent icon set, not just a collection of individual icons. Every icon should feel like it belongs alongside the rest of the library.
+Lucide is a consistent icon set, not a collection of unrelated icons. Every icon should feel like it belongs with the rest of the library.

-This guide explains the visual principles behind Lucide icons and how to apply them when designing new icons.
+This guide explains the visual rules behind Lucide icons and how to use them when designing new icons.

-For concrete requirements, see the [Icon Design Specification](./specification).
+For the full rule list, see the [icon design specification](./specification)

+## 1. Use a 24 × 24-pixel canvas

-## 1. Use a 24 × 24 pixel canvas
-
-Icons **must** be designed on a 24 × 24 pixel canvas.
+Icons **must** be designed on a 24 × 24-pixel canvas.

 :::: example
 ::: do ../../images/24px-24px.svg?raw=true
 Use a **24 × 24 pixel** canvas.
 :::
 ::: dont ../../images/24px-24px-violation.svg?raw=true
-Use a larger or smaller canvas, or one that's not square.
+Don't use a canvas that is larger, smaller, or not square.
 :::
 ::::

-
-## 2. Keep 1 pixel of safe zone
+## 2. Keep a 1-pixel safe zone

 Icons **must** have at least 1 pixel of padding between their strokes and the edge of the canvas.

@@ -34,20 +32,20 @@ Icons **must** have at least 1 pixel of padding between their strokes and the ed
 Keep at least **1 pixel of padding** around the icon.
 :::
 ::: dont ../../images/1px-padding-violation.svg?raw=true
-You must leave this safe zone, otherwise it might result in trimmed visuals.
+Don't place strokes at the edge of the canvas. They may get clipped.
 :::
 ::::

-## 3. Use 2 pixel strokes
+## 3. Use 2-pixel strokes

 Strokes **must** be 2 pixels wide.

 :::: example
 ::: do ../../images/2px-stroke.svg?raw=true
-Use a **2 pixel stroke width**.
+Use a **2-pixel stroke width**.
 :::
 ::: dont ../../images/2px-stroke-violation.svg?raw=true
-Avoid **thicker or thinner** strokes, or **mixing stroke widths**.
+Don't use **thicker or thinner** strokes, or **mix stroke widths**.
 :::
 ::::

@@ -60,12 +58,12 @@ Strokes **must** use round line joins.
 Use **round line joins**.
 :::
 ::: dont ../../images/round-joints-violation.svg?raw=true
-You **must not** use **miter or bevel** line joins.
+Don't use **miter or bevel** line joins.
 :::
 ::::

 ::: tip
-Even though round line joins are used, you should still add corner rounding to most sharp corners.
+Round joins do not replace corner rounding. Most sharp corners still need a radius.
 :::

 ## 5. Use round line caps
@@ -77,7 +75,7 @@ Open paths **must** use round line caps.
 Use **round line caps** on open paths.
 :::
 ::: dont ../../images/round-caps-violation.svg?raw=true
-You **must not** use **butt or square** line caps.
+Don't use **butt or square** line caps.
 :::
 ::::

@@ -90,7 +88,7 @@ Strokes **must** be centered on their paths.
 Keep strokes **centered** on their paths.
 :::
 ::: dont ../../images/centered-strokes-violation.svg?raw=true
-You **must not** use **inside or outside** strokes, as they alter the intended appearance of line joins.
+Don't use **inside or outside** strokes. They change how line joins look.
 :::
 ::::

@@ -103,29 +101,29 @@ Almost every sharp corner **should** be rounded.
 Use **rounded corners**.
 :::
 ::: dont ../../images/border-radius-violation.svg?raw=true
-Avoid **sharp corners**.
+Don't use **sharp corners**.
 :::
 ::::

-The corner radius depends on the size of the element and the angle. For 90° angles you should:
+Corner radius depends on the size of the element and the angle. For 90° angles:

 :::: example
 ::: do ../../images/2px-border-radius.svg?raw=true
-Use a **2 pixel corner radius** for shapes that are at least 8 pixels wide or tall.
+Use a **2-pixel corner radius** for shapes that are at least 8 pixels wide or tall.
 :::
 ::: do ../../images/1px-border-radius.svg?raw=true
-Use a **1 pixel corner radius** for shapes smaller than 8 pixels.
+Use a **1-pixel corner radius** for shapes smaller than 8 pixels.
 :::
 ::::

-But there are always exceptions to the rule:
+There are exceptions:

 :::: example
 ::: do ../../images/border-radius-90deg.svg?raw=true
-Diagonal lines meeting at a right angle are usually rounded to **2.41 pixels** (1+√2) in order for the lines to be **perfectly grid aligned**.
+Diagonal lines that meet at a right angle usually need a **2.41 pixel** radius (1+√2) to stay aligned to the grid.
 :::
 ::: do ../../images/border-radius-arbitrary.svg?raw=true
-Even **very sharp corners** should have a _minor_ amount of rounding applied, but how much exactly will vary on the geometry of the icon.
+Even **very sharp corners** usually need a small amount of rounding. The exact amount depends on the shape.
 :::
 ::::

@@ -133,14 +131,14 @@ Avoid rounding corners **where multiple lines meet**.

 :::: example
 ::: do ../../images/border-radius-line-join.svg?raw=true
-Keep corners sharp if multiple lines meet, this will ensure the icon scales in a consistent way.
+Keep corners sharp where multiple lines meet so the icon scales well.
 :::
 ::: dont ../../images/border-radius-line-join-violation.svg?raw=true
-Make icons consistent at different scales by **not rounding** corners where more than two lines meet.
+Don't round corners where more than two lines meet. This can make the icon scale poorly.
 :::
 ::::

-## 8. Keep 2 pixels of gap
+## 8. Keep at least 2 pixels between elements

 Distinct elements **must** have at least 2 pixels of visual spacing between them.

@@ -149,29 +147,29 @@ Distinct elements **must** have at least 2 pixels of visual spacing between them
 Keep **2 pixels of spacing** between distinct elements.
 :::
 ::: dont ../../images/1px-element-spacing.svg?raw=true
-Never use gaps smaller than **2 pixels** between distinct elements.
+Don't use gaps smaller than **2 pixels** between distinct elements.
 :::
 ::::

-This includes the inside of shapes, so most inner gaps **should** be at least 2 pixels wide.
+This also applies inside shapes. Most inner gaps **should** be at least 2 pixels wide.

 :::: example
 ::: do ../../images/2px-inner-spacing.svg?raw=true
 Keep at least **2 pixels of spacing** inside shapes.
 :::
 ::: dont ../../images/1px-inner-spacing.svg?raw=true
-Avoid inner gaps smaller than **2 pixels**.
+Don't use inner gaps smaller than **2 pixels**.
 :::
 ::::

-You can also visualize this rule by trying to place a **2 pixel wide circle** within your shape.
+You can test this by placing a **2-pixel-wide circle** inside your shape.

 :::: example
 ::: do ../../images/2px-inner-gap.svg?raw=true
-If a **2 pixel wide circle** fits inside the shape without overlapping, the gap is **wide enough**.
+If a **2-pixel-wide circle** fits without overlapping, the gap is **wide enough**.
 :::
 ::: dont ../../images/1px-inner-gap.svg?raw=true
-If a **2 pixel wide circle** overlaps the shape, the inner gap should be **wider**.
+If the circle overlaps the shape, the gap should be **wider**.
 :::
 ::::

@@ -179,14 +177,14 @@ The 2 pixel spacing also applies when elements visually connect or intersect.

 :::: example
 ::: dont ../../images/2px-element-spacing-connected.svg?raw=true
-Maintain 2 pixels of spacing where elements **visually connect**.
+Don't connect elements without keeping **2 pixels of spacing**.
 :::
 ::: dont ../../images/2px-element-spacing-abrupt-cut.svg?raw=true
-Avoid **abrupt cuts** where one element meets another.
+Don't use **abrupt cuts** where one element meets another.
 :::
 ::::

-## 9. Aim for uniform volume
+## 9. Aim for consistent visual weight

 Icons should have a similar visual weight when viewed alongside each other.

@@ -197,27 +195,27 @@ Match the visual weight of `circle` and `square`.
 :::

 ::: dont ../../images/visual-weight-uneven.svg?raw=true
-The second icon is **too large**, the fourth is **too small**.
+The second icon is **too large**. The fourth is **too small**.
 :::

 ::::

 ::: tip
-The amount and distribution of strokes affect how heavy an icon appears. An icon with many closely spaced elements can appear much heavier than a simpler icon, even when both use the same stroke width.
+The amount and placement of strokes affect how heavy an icon looks. An icon with many close strokes can look heavier than a simpler icon, even with the same stroke width.

-Place your icon next to `circle` or `square` and blur them. Your icon should not appear significantly lighter or darker than the reference icon.
+Place your icon next to `circle` or `square`, then blur both icons. Your icon should not look much lighter or darker than the reference icon.
 :::

 ## 10. Balance icons visually

-Icons should appear centered and balanced within the canvas.
+Icons should look centered and balanced within the canvas.

 :::: example
 ::: do ../../images/visually-centered-do.svg?raw=true
 Keep your icons visually centered.
 :::
 ::: dont ../../images/visually-centered-dont.svg?raw=true
-The optical volume of this icon is offset to the top left.
+This icon feels shifted toward the top left.
 :::
 ::::

@@ -231,61 +229,61 @@ Symmetrical icons should remain geometrically centered.
 ::::

 ::: tip
-Geometric centering does not always produce a visually centered icon. Asymmetrical shapes may need to be moved slightly to compensate for their visual center of gravity.
+Geometric centering does not always look centered. Asymmetrical shapes may need a small adjustment.

-Compare your icon with `circle` or `square` both side by side and vertically. If it appears shifted in either direction, adjust its position.
+Compare your icon with `circle` or `square` side by side and stacked vertically. If it looks shifted, adjust it.
 :::

 ## 11. Keep density low

-Lucide icons should have a similar visual density and level of detail.
+Lucide icons should have a similar level of detail.

 :::: example
 ::: do ../../images/density-optimal.svg?raw=true
-Simplify complex subjects, preserving the features that make them identifiable.
+Simplify complex subjects, but keep the features that make them recognizable.
 :::
 ::: dont ../../images/density-too-dense.svg?raw=true
-Avoid adding unnecessary details that make the design dense.
+Don't add extra details that make the design feel crowded.
 :::
 ::::

 ::: tip

-Dense areas and closely spaced strokes can also make an icon appear heavier than surrounding icons.
+Dense areas and close strokes can make an icon look heavier than nearby icons.

-View the icon at its intended size and try blurring it. Areas that become noticeably dark may contain too much detail.
+View the icon at its intended size and blur it. Areas that turn dark may have too much detail.

 :::

 ## 12. Use smooth, simple curves

-Curves should be smooth and use the simplest geometry that accurately describes the shape.
+Curves should be smooth and as simple as the shape allows.

 :::: example
 ::: do ../../images/curvature-smooth.svg?raw=true
 Prefer **simple arcs** and **quadratic curves** where possible.
 :::
 ::: dont ../../images/curvature-uneven.svg?raw=true
-Avoid **uneven or unnecessarily complex** curves.
+Don't use **uneven or unnecessarily complex** curves.
 :::
 ::::

 ::: tip
-When cubic Bézier curves are necessary, keep their control points aligned appropriately to avoid visible changes in curvature.
+When you need cubic Bézier curves, align their control points to avoid visible bumps.

-Avoid unnecessary control points. They make shapes harder to maintain and can introduce subtle irregularities.
+Avoid extra control points. They make shapes harder to edit and can create small flaws.
 :::

 ## 13. Design for the pixel grid

-Lucide icons should appear sharp and intentional at small sizes, including on low-density displays.
+Lucide icons should look sharp at small sizes, including on low-density displays.

 :::: example
 ::: do ../../images/pixel-perfection-ideal.svg?raw=true
-Align coordinates and the centers of arcs and other geometric elements to the pixel grid where possible.
+Align coordinates, arc centers, and other geometric elements to the pixel grid when possible.
 :::
 ::: dont ../../images/pixel-perfection-bad.svg?raw=true
-Avoid placing geometry off the pixel grid without a visual reason.
+Don't place geometry off the pixel grid without a visual reason.
 :::
 ::::

@@ -294,68 +292,68 @@ Avoid placing geometry off the pixel grid without a visual reason.
 Also **align subelements** to the pixel grid.
 :::
 ::: dont ../../images/pixel-perfection-subelement-dont.svg?raw=true
-You **must not** place subelements off-grid, as they'll become blurry on low density displays.
+Don't place subelements off-grid. They may become blurry on low-density displays.
 :::
 ::::

 ::: tip
-Pixel alignment should support the overall appearance of the icon rather than come at the expense of recognizable shapes, smooth curves, or visual balance.
+Pixel alignment should support the icon. Do not let it harm shape recognition, smooth curves, or visual balance.
 :::

 ## 14. Reuse established shapes

-When creating variant icons, preserve the geometry of the base icon unless the new concept requires a change.
+When creating a variant, keep the base icon geometry unless the new idea needs a change.

 :::: example
 ::: do ../../images/established-shapes-base-do.svg?raw=true
 Reuse existing base icons **exactly as they appear**.
 :::
 ::: dont ../../images/established-shapes-base-dont.svg?raw=true
-Avoid altering the **geometry, placement and orientation** of base shapes.
+Don't change the **geometry, placement, or orientation** of base shapes.
 :::
 ::::

-Related icons should share the same shapes and visual patterns wherever possible.
+Related icons should share shapes and visual patterns when possible.

 :::: example
 ::: do ../../images/established-shapes-sub-do.svg?raw=true
 Reuse elements from existing icons **without change**.
 :::
 ::: dont ../../images/established-shapes-sub-dont.svg?raw=true
-Avoid creating **new designs for existing elements**.
+Don't redesign **existing elements**.
 :::
 ::::

-Common modifiers and elements should behave and appear consistently across both icon sets and the library.
+Common modifiers and elements should look consistent across the library.

 :::: example
 ::: do ../../images/established-shapes-consistency-do.svg?raw=true
-Maintain consistency between the **placement and size** of addons.
+Keep add-ons consistent in **placement and size**.
 :::
 ::: dont ../../images/established-shapes-consistency-dont.svg?raw=true
-Avoid using **irregular placements and sizes** compared to existing icons.
+Don't use **irregular placement or size** compared to existing icons.
 :::
 ::::

 ::: tip
-Preserving the base shape also makes related icons work better when switching between them in an interface.
+Preserving the base shape makes related icons work better when users switch between them.

-Consistency with an existing icon should not override the other principles of the design language. Adjust the shape when necessary to maintain visual weight, balance, clarity, or readability.
+Consistency with an existing icon should not override clarity, balance, or readability. Adjust the shape when needed.
 :::

-## TL;DR
+## Summary

 When designing a Lucide icon:

 1. **Use a 24 × 24 pixel canvas** with at least **1 pixel of safe zone**.
 2. **Use 2 pixel centered strokes** with **round caps and joins**.
 3. **Round sharp corners** using consistent radii appropriate for their size and geometry.
-4. **Keep at least 2 pixels of gap** between distinct elements and, where possible, inside shapes.
-5. **Match the optical volume** of `circle` and `square`.
-6. **Center icons visually**, accounting for their center of gravity.
+4. **Keep at least 2 pixels of spacing** between distinct elements and, where possible, inside shapes.
+5. **Match the visual weight** of `circle` and `square`.
+6. **Center icons visually**, accounting for visual weight.
 7. **Keep visual density low** and remove unnecessary detail.
 8. **Use smooth, simple curves** without unnecessary control points.
 9. **Align geometry to the pixel grid** where possible.
-10. **Reuse established shapes and geometry** from existing Lucide icons.
+10. **Reuse established shapes** from existing Lucide icons.

-When these guidelines conflict, you should prioritize **clarity, visual balance, and consistency** with the rest of the Lucide set.
+When these guidelines conflict, prioritize **clarity, visual balance, and consistency** with the rest of Lucide.
--- a/docs/contribute/icons/figma-guide.md
+++ b/docs/contribute/icons/figma-guide.md
@@ -1,55 +1,60 @@
 ---
-description: Learn how to use Figma for creating icons for Lucide.
+description: Learn how to create Lucide icons in Figma.
 ---

 # Figma template guide

-This guide shows the steps to set up Figma for creating icons that conform to the Lucide design guidelines.
+This guide shows how to set up Figma for Lucide icons.

-## Setting up the frame
+## Set 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.
+Create each icon in its own frame.

-To do this, create a frame of 24x24 pixels.
+Use a `24 × 24` pixel frame.

-1. Click the frame button (or press `F`)
-2. Draw a 24x24 frame (or edit it afterwards from the design window)
+1. Click the frame button, or press `F`.
+2. Draw a `24 × 24` frame, or set the size in the right sidebar.

-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`.
+Design the icon inside this frame. Name the frame after the icon so Figma exports it as `frame-name.svg`.

 ## Create your icon

-To design your icon in the style of Feather Icons, you need to adjust a few settings in Figma.
+Set up the stroke before drawing.

-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.
+Draw in the frame with the pen tool. Open it from the toolbar or press `P`. After you start drawing, adjust the vector settings in the right sidebar.

 Set the following:
+
 1. Vector
   1. Corner radius: 2px
 2. Stroke
   1. Stroke width: 2px
   2. Stroke alignment: center

-![Figma Stroke Options](../../images/figma-stroke-options.png)
+![Figma stroke options](../../images/figma-stroke-options.png)

 ## Export or copy your icon

-Once you have completed your icon, you can export it.
+When your icon is ready, export it.

-1. Select the frame
-2. Open the *Export* tab on the right
-3. Set the file type as SVG
-4. Press export
+1. Select the frame.
+2. Open the _Export_ section in the right sidebar.
+3. Set the file type to SVG.
+4. Click _Export_.

-Or you can also copy its source as SVG.
+You can also copy the SVG source.

-1. Select the frame
-2. Right click it
-3. Click on *Copy/Paste as*
-4. Click on *Copy as SVG*
+1. Select the frame.
+2. Right-click it.
+3. Choose _Copy/Paste as_.
+4. Choose _Copy as SVG_.

-That's it. You just made your first icon. Congratulations!
+You now have an SVG to prepare for contribution.

-## Figma tip
+## Optimize your icon

-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).
+You can optimize the exported SVG with [Lucide Studio](https://studio.lucide.dev/).
+
+## Check spacing in Figma
+
+The [design language](design-principles.md) requires at least 2 pixels of spacing between separate elements. In Figma, hold `Option` on macOS or `Alt` on Windows to check spacing.
--- a/docs/contribute/icons/illustrator-guide.md
+++ b/docs/contribute/icons/illustrator-guide.md
@@ -1,31 +1,27 @@
 ---
-description: Learn how to properly use the Adobe Illustrator template for Lucide.
+description: Learn how to use the Adobe Illustrator template for Lucide.
 ---

 # Adobe Illustrator template guide

-This guide explains how to properly use the Adobe Illustrator template for Lucide.
+This guide explains how to 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.
+> Templates can fall out of date. Check the [design language](design-principles.md) before you start.

-## General workflow
+## Workflow

-The Illustrator template is created following guidelines from the [Icon Design Guide](design-principles.md).
-
-**Workflow:**
+The Illustrator template follows the [design language](design-principles.md).

 1. Download and open the [Illustrator template](https://github.com/lucide-icons/lucide/blob/main/docs/public/templates/illustrator_template.ai).

-2. You can now remove the content from the example logo layer ("Draw") and start creating.
+2. Remove the content from the example logo layer (`Draw`) and start drawing.

-3. Verify that you follow the [Icon Design Guidelines](design-principles.md).
+3. Check that your icon follows the [design language](design-principles.md).

-4. Before you export the file as an SVG make sure to check that you followed the guidelines and remove all unnecessary layers (especially "Padding" and "Grid").
+4. Before export, remove unnecessary layers, especially `Padding` and `Grid`.

-5. Export the file with the export menu under: `Export > Export As..` then save the file as SVG. Select the following options in the SVG Options dialog:
+5. Export the file with `Export > Export As...`, then save it as SVG. Use these SVG options:

-![SVG export options in Illustrator](../../images/illustrator-svg-options.png?raw=true "Setting Page Size")
+   ![SVG export options in Illustrator](../../images/illustrator-svg-options.png?raw=true 'SVG export options in Illustrator')

-After that, double check that the [code conventions and SVG global attributes](code-conventions.md) are correct.
-
-7. Minify paths with [SVGOMG](https://jakearchibald.github.io/svgomg/).
+6. Optimize your SVG with [Lucide Studio](https://studio.lucide.dev/)
--- a/docs/contribute/icons/index.md
+++ b/docs/contribute/icons/index.md
@@ -1,6 +1,7 @@
 ---
 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';
@@ -9,26 +10,26 @@ import { resourcesSidebar } from '../../.vitepress/sidebar/resources.ts';

 # Designing icons for Lucide

-Within any icon set, every icon should feel like it belongs alongside the rest of the library.
+Every icon should feel like it belongs with the rest of Lucide.

-This guide explains how to design and prepare icons for contribution to Lucide.
+This guide explains how to design and prepare icons for Lucide.

-## What's in this guide?
+## What this guide covers

 <OverviewLinkGrid>
  <OverviewLink v-for="item in resourcesSidebar[2].items.slice(1, -1)" :key="item.link" :href="item.link" :title="item.text" :desc="item.desc"/>
 </OverviewLinkGrid>

-## Designing icons with your preferred software
+## Use your preferred design tool

-You do not need to use any particular design software, you can design Lucide icons with any vector graphics editor that can export SVG.
+You can design Lucide icons with any vector editor that can export SVG.

-We provide step-by-step guides for the following common tools:
+Use these step-by-step guides for common tools:

 <OverviewLinkGrid>
  <OverviewLink v-for="item in resourcesSidebar[2].items.at(-1).items" :key="item.link" :href="item.link" :title="item.text" :desc="item.desc"/>
 </OverviewLinkGrid>

-These guides explain how to set up your document, work within the Lucide design constraints, and export an SVG suitable for contribution.
+These guides explain how to set up your document, follow the Lucide rules, and export a usable SVG.

 Regardless of which tool you use, the same design and SVG requirements apply.
--- a/docs/contribute/icons/inkscape-guide.md
+++ b/docs/contribute/icons/inkscape-guide.md
@@ -1,40 +1,42 @@
 ---
-description: Learn how to set up Inkscape for creating icons for Lucide.
+description: Learn how to create Lucide icons in Inkscape.
 ---

-# Inkscape Setup Guide
+# Inkscape setup guide

-This guide shows the steps to set up Inkscape for creating icons that conform to the Lucide design guidelines.
+This guide shows how to set up Inkscape for Lucide icons.

-## Setting up The Canvas
+## Set up the canvas

-When opening a new document, Inkscape will create a canvas of a default size.  To change the size to 24x24:
+Inkscape creates new documents with a default canvas size. Change it to `24 × 24` pixels:

-1. Open the Document Properties dialog (File -> Document Properties).
-2. On the “Page Size” tab, under “Custom Size” set the Units to `px` and set both Height and Width to 24.
-![Setting Page Size](../../images/page-size.png?raw=true "Setting Page Size")
-3. On the “Grid” tab, select `Rectangular Grid` and click “New Grid”.
-![Setting Grid Properties](../../images/grid-1.png?raw=true "Setting Grid Properties")
-4. Set the Grid Units to `px` and set Spacing X and Spacing Y both to 1.
-![Setting Grid Properties](../../images/grid-2.png?raw=true "Setting Grid Properties")
+1. Open the Document Properties dialog with `File > Document Properties`.
+2. On the _Page Size_ tab, under _Custom Size_, set units to `px` and set width and height to `24`.
+   ![Setting page size](../../images/page-size.png?raw=true 'Setting page size')
+3. On the _Grid_ tab, select `Rectangular Grid` and click _New Grid_.
+   ![Setting grid properties](../../images/grid-1.png?raw=true 'Setting grid properties')
+4. Set grid units to `px`, then set `Spacing X` and `Spacing Y` to `1`.
+   ![Setting grid properties](../../images/grid-2.png?raw=true 'Setting grid properties')
 5. Close the Document Properties dialog.
-6. To center the canvas in the viewport, select View -> Zoom -> Drawing.
+6. To center the canvas in the viewport, select `View > Zoom > Drawing`.

-## Setting up The Paths
+## Set up paths

 1. Create a path or shape.
-2. With the path selected, open the Stroke and Fill panel by pressing `Ctrl+Shift+F` on your keyboard.
-![Stroke Style Properties](../../images/strokes.png?raw=true "Setting Grid Properties")
-3. On the “Stroke Style” tab:
-   * Set Stroke Width to `2px`.
-   * Select the rounded join type.
-   * Select the rounded cap type.
-4. If the shape is a rectangle, select the rectangle and in the top of the screen below the menu bar, set `Rx` and `Ry` to `2px`.
-![Rectangle Radius Properties](../../images/corner-radius.png?raw=true "Rectangle Radius Properties")
+2. With the path selected, press `Ctrl+Shift+F` to open the Stroke and Fill panel.
+   ![Stroke style properties](../../images/strokes.png?raw=true 'Setting grid properties')
+3. On the _Stroke Style_ tab:
+   - Set stroke width to `2px`.
+   - Select the rounded join type.
+   - Select the rounded cap type.
+4. For rectangles, select the rectangle and set `Rx` and `Ry` to `2px` in the toolbar.
+   ![Rectangle radius properties](../../images/corner-radius.png?raw=true 'Rectangle radius properties')

-## Saving A File
+## Save a file

-1. When ready to save the file, click Save As and select “Optimized SVG” as the file type.
-![Save As](../../images/save-as.png?raw=true "Save as")
-2. After clicking Save, to conform with the other icons in the package, set Pretty Printing to use spaces and set the indentation depth to 2.
-![Optimize](../../images/optimize-settings.png?raw=true "Optimize")
+1. When you are ready, click _Save As_ and choose _Optimized SVG_ as the file type.
+   ![Save as](../../images/save-as.png?raw=true 'Save as')
+
+## Optimize your icon
+
+As a final step, optimize your SVG with [Lucide Studio](https://studio.lucide.dev/).
--- a/docs/contribute/icons/metadata-conventions/index.md
+++ b/docs/contribute/icons/metadata-conventions/index.md
@@ -9,9 +9,9 @@ import OverviewLinkGrid from '../../../.vitepress/theme/components/base/Overview

 # 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.
+Every Lucide icon has a matching JSON metadata file. Metadata credits contributors, groups icons, improves search, and explains where an icon is useful.

-Use this guide when adding a new icon or reviewing metadata for an existing icon.
+Use this guide when you add a new icon or review existing metadata.

 ## Metadata file location

@@ -23,7 +23,7 @@ The JSON file must use the same base name as the SVG file:
 - `arrow-up.svg` -> `arrow-up.json`
 - `square-parking.svg` -> `square-parking.json`

-All icon metadata files are validated against `icon.schema.json`.
+All icon metadata files must pass `icon.schema.json`.

 ## Required fields

@@ -40,44 +40,34 @@ A minimal metadata file looks like this:
 ```json
 {
  "$schema": "../icon.schema.json",
-  "contributors": [
-    "github-username",
-    "another-github-username"
-  ],
-  "use-cases": [
-    "Representing example items in an interface"
-  ],
-  "tags": [
-    "foo",
-    "bar"
-  ],
-  "categories": [
-    "devices"
-  ]
+  "contributors": ["github-username", "another-github-username"],
+  "use-cases": ["Representing example items in an interface"],
+  "tags": ["foo", "bar"],
+  "categories": ["devices"]
 }
 ```

 ## Contributors

-The `contributors` field is a list of GitHub usernames for people who created or meaningfully contributed to the icon.
+The `contributors` field lists GitHub usernames for people who created or meaningfully changed 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.
+2. Add a username when someone made a significant change to the icon design.
 3. Do not add people for minor review comments, metadata-only edits, or unrelated discussion.

 ## Use cases

-The `use-cases` field explains where and why an icon would be used in a real interface.
+The `use-cases` field explains where and why someone would use the icon in an interface.

-Use cases should be short phrases, not full sentences. Start with a present participle verb such as:
+Use cases should be short phrases, not full sentences. Start with an `-ing` verb, such as:

- Representing...
- Indicating...
- Marking...
- Showing...
- Toggling...
+- Representing [concept]
+- Indicating [state]
+- Marking [item]
+- Showing [information]
+- Toggling [setting]

 ### Use case rules

@@ -87,8 +77,8 @@ Use cases should be short phrases, not full sentences. Start with a present part
 - 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
+- Do not add Markdown or emoji
+- Do not add implementation details or pull request references

 <OverviewLinkGrid>
  <OverviewLink href="./use-case-guide.md" title="Use case guide" desc="Learn the best practices for writing use cases"/>
@@ -98,9 +88,9 @@ Use cases should be short phrases, not full sentences. Start with a present part

 The `tags` field is a list of search terms for the icon.

-Tags should describe concepts, synonyms, related terms, and common contexts that help people find the icon.
+Tags should describe concepts, synonyms, related terms, and common contexts.

-Use existing tags in the repository as a reference before adding new ones. This keeps search behavior consistent and avoids unnecessary duplicates.
+Check existing tags before adding new ones. This keeps search consistent and avoids duplicates.

 ### Tag rules

@@ -111,7 +101,7 @@ Use existing tags in the repository as a reference before adding new ones. This
 - Do not add generic tags like `icon`.
 - Do not add unrelated concepts just to increase search coverage.

-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.
+For example, `mail-search` can use tags like `email`, `message`, `letter`, `find`, and `filter`, but not `mail`, `search` or `mail search`.

 <OverviewLinkGrid>
  <OverviewLink href="./tag-guide.md" title="Tag guide" desc="Learn the best practices for writing tags"/>
@@ -119,11 +109,11 @@ For example, a `mail-search` icon can use tags such as `email`, `message`, `lett

 ## Categories

-The `categories` field groups icons into broad areas of use.
+The `categories` field groups icons by broad use.

 Categories must come from the allowed category list in `icon.schema.json`.

-Choose categories based on what the icon represents and where it is commonly used. Use existing icon metadata as a reference for similar icons.
+Choose categories based on what the icon represents and where people use it. Check similar icons first.

 ### Category rules

@@ -134,7 +124,7 @@ Choose categories based on what the icon represents and where it is commonly use

 ## Variants and related icons

-Related icons should have related metadata, but they should not blindly share identical use cases.
+Related icons should have related metadata, but do not copy use cases blindly.

 Write metadata for the specific variant:

@@ -143,13 +133,13 @@ Write metadata for the specific variant:
 - `square-arrow-right-enter` -> sign in, enter, or join contexts
 - `square-arrow-right-exit` -> sign out, exit, or export contexts

-When a request covers several icons at once, only assign a use case to the icon it actually describes. Do not let metadata from one icon leak into another icon in the same group.
+When a request covers several icons, assign each use case only to the icon it describes. Do not copy metadata to icons it does not describe.

 ## Aliases

 Some icons can include an optional `aliases` field for alternate names.

-For the present, we only add aliases to icons when renaming them from non-compliant names.
+Only add aliases when an icon has been renamed from a non-compliant name.

 ## Validation

@@ -167,7 +157,7 @@ pnpm exec prettier "icons/*.json" --check

 ## Checklist

-Before opening a PR, confirm that:
+Before opening a pull request, confirm that:

 - The JSON file name matches the SVG file name.
 - The file includes all required fields.
--- a/docs/contribute/icons/metadata-conventions/tag-guide.md
+++ b/docs/contribute/icons/metadata-conventions/tag-guide.md
@@ -9,13 +9,13 @@ import LucideIcon from '~/.vitepress/theme/components/base/LucideIcon.vue';

 # Tag guide

-This guide will teach you how to write useful search tags for Lucide icons.
+This guide shows 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.
+Tags help people find icons by concept, synonym, context, or common wording.

 ## Use lowercase tags

-Tags should always be lowercase so search metadata stays consistent.
+Tags should always be lowercase.

 :::: example
 ::: do <LucideIcon :iconNode="mail" /> email
@@ -28,11 +28,11 @@ 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.
+Use one clear word when it is enough. Use multi-word tags when the phrase is clearer.

 :::: example
 ::: do <LucideIcon :iconNode="search" /> search
-This is **short, common, and easy to match** in search.
+This is **short, common, and easy to find**.
 :::
 ::: dont <LucideIcon :iconNode="search" /> searching through files & folders
 This reads like a **use case**, not a tag.
@@ -41,7 +41,7 @@ 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.
+Some ideas are only clear as a phrase. But keep those phrases short.

 :::: example
 ::: do <LucideIcon :iconNode="droplet" /> blood type
@@ -54,7 +54,7 @@ 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.
+Tags can include words people are likely to search for, even if they are not in the icon name.

 :::: example
 ::: do <LucideIcon :iconNode="mail" /> email
@@ -67,7 +67,7 @@ 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.
+The icon name is already searchable. Tags should add other ways to find it.

 :::: example
 ::: do <LucideIcon :iconNode="mailSearch" /> message filter
@@ -80,11 +80,11 @@ 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.
+Tags should describe the icon, not say that it is an icon.

 :::: example
 ::: do <LucideIcon :iconNode="calendar" /> event
-This points to a **concrete concept** users might search for.
+This points to a **specific idea** 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.
@@ -93,11 +93,11 @@ This points to a **concrete concept** users might search for.

 ## Keep tags relevant

-Do not add loosely related terms just to make an icon appear in more searches.
+Do not add loose 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.
+This is **relevant** for an icon that marks emergency room locations.
 :::
 ::: dont <LucideIcon :iconNode="hospital" /> doctor nurse pharmacy
 These terms may be **nearby concepts**, but they do not all describe the same icon.
@@ -106,26 +106,26 @@ These terms may be **nearby concepts**, but they do not all describe the same ic

 ## Match the specific variant

-Related icons should share useful family terms, but variant tags should describe what is different.
+Related icons can share 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`.
+This describes `battery-full` better than `battery-low`.
 :::
 ::::

 ## Use existing tags as a reference

-Check similar icons before inventing new tags. Reusing established terms keeps search behavior predictable.
+Check similar icons before adding new tags. Reusing existing terms keeps search predictable.

 :::: example
 ::: do <LucideIcon :iconNode="type" /> typography
-This matches existing text-formatting icons and keeps **related icons** grouped in search.
+This matches existing text-formatting icons and keeps **related icons** together in search.
 :::
 ::: dont <LucideIcon :iconNode="type" /> fontography
-Inventing a new term makes the icon harder to find and **less consistent** with nearby metadata.
+Inventing a new term makes the icon harder to find and less consistent with related metadata.
 :::
 ::::
--- a/docs/contribute/icons/metadata-conventions/use-case-guide.md
+++ b/docs/contribute/icons/metadata-conventions/use-case-guide.md
@@ -9,28 +9,28 @@ import LucideIcon from '~/.vitepress/theme/components/base/LucideIcon.vue';

 # Use case guide

-This guide will teach you how to write the best use cases for Lucide icons.
+This guide shows how to write clear 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.
+Describe what the interface tells the user. Do not write from the contributor's point of view.

 :::: example
 ::: do <LucideIcon :iconNode="wifiOff" /> Indicating a device is offline or unreachable
 This describes the **role the icon plays in an interface**.
 :::
 ::: dont <LucideIcon :iconNode="wifiOff" /> I need an icon for my offline device screen
-This explains the **contributor's situation**, not the icon's reusable purpose.
+This explains the **contributor's situation**, not the icon's 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.
+A use case should explain what the icon means in context. Do not repeat the icon name or only describe the drawing.

 :::: example
 ::: do <LucideIcon :iconNode="microchip" /> Representing processors, chips, or embedded hardware
-This makes `microchip` useful in search and documentation **without restating the name**.
+This explains `microchip` **without repeating the name**.
 :::
 ::: dont <LucideIcon :iconNode="microchip" /> it's a microchip icon
 This **duplicates the icon name** and does not explain where the icon would be used.
@@ -39,59 +39,59 @@ This **duplicates the icon name** and does not explain where the icon would be u

 ## Add context when it clarifies meaning

-Some icons have broad meanings. Add a short context when it makes the use case easier to understand.
+Some icons have broad meanings. Add context when it makes the use case clearer.

 :::: example
 ::: do <LucideIcon :iconNode="heading2" /> Applying a level-2 heading in text editors
 The phrase explains both the **action and the product area**.
 :::
 ::: dont <LucideIcon :iconNode="heading2" /> Applying a heading
-This is understandable, but less useful because it **omits the level and interface context**.
+This is less useful because it **omits the level and context**.
 :::
 ::::

 ## Keep each use case focused

-Each entry should contain one clear idea. Split genuinely different meanings into separate entries.
+Each entry should cover one clear idea. Split different meanings into separate entries.

 :::: example
 ::: do <LucideIcon :iconNode="squareParking" /> Marking parking locations on maps
-This is **short, concrete, and focused** on one interface function.
+This is **short, clear, and focused** on one interface function.
 :::
 ::: dont <LucideIcon :iconNode="squareParking" /> Marking parking, transport, maps, cars, garages, and places
-This reads like a **tag list** and **mixes several concepts** into one use case.
+This reads like a **tag list** and **mixes several ideas**.
 :::
 ::::

 ## Write variant-specific use cases

-Related icons should describe what makes each variant different.
+For related icons, describe what makes each variant different.

 :::: example
 ::: do <LucideIcon :iconNode="batteryLow" /> Indicating a low battery charge level
-This is specific to `battery-low` and **distinguishes** it from other battery icons.
+This is specific to `battery-low` and **sets it apart** from other battery icons.
 :::
 ::: dont <LucideIcon :iconNode="batteryLow" /> Representing battery status
 This is **too generic** and could apply to **every battery variant**.
 :::
 ::::

-## Avoid references that only make sense in a PR
+## Avoid pull request references

-Use cases should stand on their own after the PR is merged.
+Use cases should make sense after the pull request is merged.

 :::: example
 ::: do <LucideIcon :iconNode="handshake" /> Signifying a deal, agreement, or partnership
-This preserves the **useful meaning** without depending on **outside context**.
+This keeps the **useful meaning** without depending on **outside context**.
 :::
 ::: dont <LucideIcon :iconNode="handshake" /> Same as above in #1234
-This **depends on a discussion** that readers **may never see**.
+This **depends on a discussion** readers **may never see**.
 :::
 ::::

 ## Keep entries concise

-Use cases should usually be 4 to 12 words. Prefer one strong phrase over a long explanation.
+Use cases should usually be 4 to 12 words. Prefer a short phrase over a long explanation.

 :::: example
 ::: do <LucideIcon :iconNode="search" /> Searching files by name or content
@@ -121,22 +121,22 @@ Use plain text only. Formatting belongs in documentation, not metadata values.

 :::: example
 ::: do <LucideIcon :iconNode="triangleAlert" /> Warning users about a destructive action
-This works in search, generated pages, and other **metadata consumers**.
+This works in search, generated pages, and other places that use metadata.
 :::
 ::: dont <LucideIcon :iconNode="triangleAlert" /> <span>**Warning** users about a destructive action ⚠️</span>
-Markdown and emoji can **leak into generated UI** and make metadata **harder to reuse**.
+Markdown and emoji can **show up in generated UI** and make metadata **harder to reuse**.
 :::
 ::::

 ## Avoid implementation details

-Use cases should describe meaning, not how the SVG was built.
+Use cases should describe meaning, not how the SVG was made.

 :::: example
 ::: do <LucideIcon :iconNode="crop" /> Representing cropped or trimmed content
 This explains the icon's **interface meaning**.
 :::
 ::: dont <LucideIcon :iconNode="crop" /> 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.
+This describes **construction details** that do not help people find or understand the icon.
 :::
 ::::
--- a/docs/contribute/icons/naming-conventions.md
+++ b/docs/contribute/icons/naming-conventions.md
@@ -47,9 +47,9 @@ const pencilRulerVertical = [

 # Naming conventions

-Learn how to choose clear and consistent names for Lucide icons.
+Learn how to choose clear, consistent names for Lucide icons.

-This section covers general naming rules, word order, modifiers, variants, related icons, and other conventions used to keep icon names predictable across the library.
+This page covers word order, modifiers, variants, related icons, and other rules that keep icon names predictable.

 Use this when naming a new icon or reviewing a proposed name.

@@ -68,7 +68,7 @@ Avoid other naming schemes.

 ## 2. Use American English

-Icon names **must** use American English names, as opposed to local variants.
+Icon names **must** use American English, not local variants.

 :::: example
 ::: do <span>`color`, `maximize`, `center`</span>
@@ -79,11 +79,11 @@ Icon names **must** use American English names, as opposed to local variants.

 ## 3. Name icons for what they depict

-Icon names **must** describe what the icon depicts, not its intended use or meaning.
+Icon names **must** describe what the icon shows, not how someone might use it.

 :::: example
 ::: do <LucideIcon :iconNode="save" /> `floppy-disk`
-The icon **depicts** a floppy disk.
+The icon **shows** a floppy disk.
 :::
 ::: dont <LucideIcon :iconNode="save" /> `save`
 Save is a use case.
@@ -92,7 +92,7 @@ Save is a use case.

 :::: example
 ::: do <LucideIcon :iconNode="ban" /> `circle-slash`
-The icon **depicts** a circle with a slash across it.
+The icon **shows** a circle with a slash across it.
 :::
 ::: dont <LucideIcon :iconNode="ban" /> `ban`
 Ban is an action.
@@ -100,16 +100,14 @@ Ban is an action.
 ::::

 ::: tip
-An icon can represent different actions or concepts depending on where and how it is used. Naming
-icons for their visual appearance keeps names unambiguous and independent of their use case.
+An icon can mean different things in different products. Naming icons by appearance keeps names clear and independent from use cases.
 :::

 ## 4. Name related icons consistently

 Icons that belong to the same group **must** use the `<group>-<variant>` naming scheme.

-The group name comes first, followed by the part that distinguishes the icon from the rest of the
-group.
+The group name comes first. The variant comes after it.

 :::: example
 ::: do <span><LucideIcon :iconNode="badgePlus" /> + <LucideIcon :iconNode="badgeCheck" /></span> <span>`badge-plus` & `badge-check`</span>
@@ -122,28 +120,27 @@ group.

 ## 5. Describe alternate icons

-Alternate versions of an icon **must** be named for what makes them visually distinct. They **must
-not** use numbers merely to distinguish one version from another.
+Alternate versions of an icon **must** be named for what makes them visually different. Do **not** use numbers just to separate one version from another.

 :::: example
 ::: do <LucideIcon :iconNode="sendHorizontal" /> `send-horizontal`
 The icon depicts a horizontal "send" symbol.
 :::
 ::: dont <LucideIcon :iconNode="sendHorizontal" /> <span>`send-2` or `send-alt`</span>
-"send no. 2" or "alternative send" are not descriptive names.
+"send number 2" and "alternative send" are not clear names.
 :::
 ::::

 ## 6. Only use numerals when depicted

-Icon names **must not** contain numerals unless the numeral itself is depicted in the icon.
+Icon names **must not** include numbers unless the icon shows the number.

 :::: example
 ::: do <LucideIcon :iconNode="arrowDown01" /> `arrow-down-0-1`
 The arrow points from 0 to 1.
 :::
 ::: dont <LucideIcon :iconNode="sendHorizontal" /> `send-2`
-The icon doesn't feature the number 2.
+The icon does not show the number 2.
 :::
 ::::

@@ -152,15 +149,15 @@ The icon doesn't feature the number 2.
 The hands point to 3 o'clock.
 :::
 ::: dont <LucideIcon :iconNode="userRound" /> `user-3`
-The icon doesn't feature the number 3.
+The icon does not show the number 3.
 :::
 ::::

-Numerals must not be used to distinguish between otherwise similarly named icons.
+Do not use numbers to separate similar icons.

 ## 7. Order elements by size

-When an icon depicts multiple elements of different sizes, their names **must** be ordered from largest to smallest.
+When an icon shows multiple elements of different sizes, order their names from largest to smallest.

 For an icon containing a circle and a person:

@@ -183,62 +180,59 @@ If they do not overlap, name them in English reading order: top to bottom, then

 :::: example
 ::: do <LucideIcon :iconNode="pencilRuler" /> `pencil-ruler`
-The `pencil` is **in front** of the `ruler`, so **it takes precedence**.
+The `pencil` is **in front** of the `ruler`, so it comes first.
 :::
 ::: do <LucideIcon :iconNode="rulerDimensionLine" /> `ruler-dimension-line`
-While the ruler is below the dimension line, it is **reasonably larger**, so it should be listed first.
+The ruler is below the dimension line, but it is **larger**, so it comes first.
 :::
 ::::

 :::: example
 ::: do <LucideIcon :iconNode="sunSnow" /> `sun-snow`
-The `sun` is **left of** the `snowflake`, so **it should be listed first**.
+The `sun` is **left of** the `snowflake`, so it comes first.
 :::
 ::: dont <LucideIcon :iconNode="pencilRulerHorizontal" /> `ruler-pencil`
-The `ruler` is **below** the `pencil`, so `pencil-ruler` would be the correct name.
+The `ruler` is **below** the `pencil`, so `pencil-ruler` is the correct name.
 :::
 ::::

 ## 9. Place modifiers after the element they describe

-Modifiers **must** follow the element they describe, using the `<element>-<modifier>` naming scheme.
+Modifiers **must** come after the element they describe: `<element>-<modifier>`.

 :::: example
 ::: do <LucideIcon :iconNode="heartCrack" /> `heart-broken`
-The icon depicts a heart that is **cracked**.
+The icon shows a heart that is **cracked**.
 :::
 ::: dont <LucideIcon :iconNode="boneFracture" /> `broken-bone`
-The icon depicts a bone that is **broken**, so it should be `bone-broken`.
+The icon shows a bone that is **broken**, so name it `bone-broken`.
 :::
 ::::

-When an icon contains multiple modified elements, each modifier **must** follow its respective element.
+When an icon has multiple modified elements, each modifier **must** follow the element it describes.

 :::: example
 ::: do <LucideIcon :iconNode="circleFadingArrowUp" /> `circle-fading-arrow-up`
-The icon depicts a circle, which is **fading**, inside it is an arrow pointing **up**.
- `circle` comes first, because it is larger than `arrow`
- `fading` follows `circle` because it modifies the circle.
- `up` follows `arrow` because it modifies the arrow.
+The icon shows a **fading** circle with an arrow pointing **up** inside it.
+
+`circle` comes first because it is larger than `arrow`. `fading` follows `circle` because it modifies the circle. `up` follows `arrow` because it modifies the arrow.
 :::
 ::: dont <LucideIcon :iconNode="notepadTextDashed" /> `notepad-text-dashed`
-This icon depicting a dashed notebook with text inside should be named `notepad-dashed-text`.
- `notepad` comes first, because it is larger than `text`
- `dashed` follows `notepad` because it modifies the notepad.
- `text` should follow both `notepad` and `dashed`, because `dashed` does not modify `text`.
+This icon shows a dashed notepad with text inside, so name it `notepad-dashed-text`.
+
+`notepad` comes first because it is larger than `text`. `dashed` follows `notepad` because it modifies the notepad. `text` follows both because `dashed` does not modify `text`.
 :::
 ::::

-## TL;DR
+## Summary

 When naming an icon:

-1. **Describe what you see**, not what the icon could mean or be used for.
+1. **Describe what you see**, not what the icon could mean.
 2. **Use American English** and **lowercase kebab-case**.
-3. **Keep related icons together** using `<group>-<variant>`.
+3. **Keep related icons together** with `<group>-<variant>`.
 4. **Describe what makes an alternate unique** instead of numbering it.
 5. **Only use numerals when they are depicted** in the icon.
 6. **Order elements from largest to smallest**.
-7. If elements are roughly the same size, order them **front to back**, or otherwise in **English
-   reading order**.
+7. If elements are roughly the same size, order them **front to back**, or otherwise in **English reading order**.
 8. **Place modifiers after the element they describe**: `<element>-<modifier>`.
--- a/docs/contribute/icons/specification.md
+++ b/docs/contribute/icons/specification.md
@@ -1,25 +1,25 @@
 ---
-description: Technical specification and conformance requirements for Lucide icons.
+description: Rules Lucide icons must follow.
 ---

-# Icon Design Specification
+# Icon design specification

-This document defines the requirements for icons included in Lucide.
+This page lists the rules Lucide icons must follow.

-For explanations, examples, and guidance on applying these requirements, see the [Lucide Design Language](./design-principles).
+For examples and guidance, see the [Lucide design language](./design-principles).

-## Conformance
+## Requirement levels

-The words **must**, **must not**, **should**, and **should not** indicate the requirement level of each rule:
+These terms show how strictly each rule applies:

- **Must** and **must not** define requirements that an icon is expected to meet.
- **Should** and **should not** define requirements that may be deviated from when necessary to produce a better icon.
+- **Must** and **must not** mark required rules.
+- **Should** and **should not** mark rules that can flex when needed to make a better icon.

-Any deviation should be intentional and consistent with the [Lucide Design Language](./design-principles).
+Any exception should be intentional and fit the [Lucide design language](./design-principles).

 ## Canvas

-1. Icons **must** use a 24 × 24 pixel canvas.
+1. Icons **must** use a 24 × 24-pixel canvas.
 2. The canvas **must** be square.
 3. Icon strokes **must** remain at least 1 pixel from the edge of the canvas.

@@ -33,8 +33,8 @@ Any deviation should be intentional and consistent with the [Lucide Design Langu
 ## Corners

 1. Sharp corners **should** be rounded unless the geometry of the icon requires otherwise.
-2. Elements at least 8 pixels wide or tall **should** use a 2 pixel corner radius for 90° corners.
-3. Elements smaller than 8 pixels **should** use a 1 pixel corner radius for 90° corners.
+2. Elements at least 8 pixels wide or tall **should** use a 2-pixel corner radius for 90° corners.
+3. Elements smaller than 8 pixels **should** use a 1-pixel corner radius for 90° corners.
 4. Diagonal lines meeting at a 90° angle **should** use a radius that preserves pixel-grid alignment. This radius is typically approximately 2.41 pixels.
 5. Acute corners **should** use an appropriate amount of rounding based on their geometry.
 6. Corners where multiple lines meet **should** remain sharp when rounding would cause the icon to render inconsistently at different sizes.
@@ -47,20 +47,20 @@ Any deviation should be intentional and consistent with the [Lucide Design Langu
 4. Spacing **should** remain visually consistent where elements connect or intersect.
 5. Elements **should not** terminate with an abrupt cut where another element visually continues or intersects them.

-## Optical volume
+## Visual weight

-1. Icons **should** have an optical volume comparable to the `circle` and `square` icons.
+1. Icons **should** have a visual weight similar to the `circle` and `square` icons.
 2. Icons **should not** appear substantially larger, smaller, heavier, or lighter than comparable Lucide icons.

 ## Alignment and balance

 1. Icons **should** be visually centered within the canvas.
-2. Asymmetrical icons **may** be positioned off their geometric center to compensate for their visual center of gravity.
+2. Asymmetrical icons **may** be moved slightly off center so they look visually centered.
 3. Symmetrical icons **should** be geometrically centered.

 ## Visual density

-1. Icons **should** maintain a level of visual density comparable to other Lucide icons.
+1. Icons **should** have a level of detail similar to other Lucide icons.
 2. Details **should** be simplified when they cause an icon to appear substantially denser than comparable icons.
 3. Details that are not necessary for recognition **should** be omitted.

@@ -85,11 +85,11 @@ Any deviation should be intentional and consistent with the [Lucide Design Langu
 1. Variants of an existing icon **should** preserve the geometry, placement, and orientation of the base icon.
 2. Elements that already exist in other Lucide icons **should** reuse established geometry where applicable.
 3. Related icons **should** use consistent representations of shared elements.
-4. Common modifiers and addons **should** use consistent geometry, size, and placement across related icons.
-5. Existing geometry **may** be modified when necessary to satisfy other requirements of the Lucide Design Language.
+4. Common modifiers and add-ons **should** use consistent geometry, size, and placement across related icons.
+5. Existing geometry **may** be modified when necessary to satisfy other Lucide design language rules.

 ## Priority of requirements

-When two non-mandatory requirements conflict, visual clarity and consistency with the Lucide Design Language should take precedence over mechanical adherence to an individual rule.
+When two non-required rules conflict, choose visual clarity and consistency with the Lucide design language.

-Requirements marked **must** or **must not** may only be deviated from where an exception is explicitly defined by the project.
+Rules marked **must** or **must not** can only be broken when the project defines an explicit exception.