docs: update Lucide icons docs guidelines

Author: wackerow

docs/best-practices.md

@@ -166,15 +166,74 @@ import Emoji from "./Emoji"
 ;<Emoji text=":star:" fontSize="xl" /> // the base fontSize is `md`
 ```
 
-- **Icons**: We use [Lucide](https://lucide.dev/icons/) for icons
+## Icons: Lucide
+
+We use [Lucide](https://lucide.dev/icons/) for icons, imported via the [lucide-react](https://www.npmjs.com/package/lucide-react) package.
+
+Lucide icons by default use strokes only, with default 2px stroke width, rounded line-caps and line-joins, and follow `currentColor`.
+
+### Basic Usage
+
+```tsx
+import { Heart } from "lucide-react"
+;<Heart />
+```
+
+### Sizing
+
+Use tailwind classes to size icons:
+
+- **Static**: example: `size-6` (24px), `size-4` (16px), etc.
+- **Mirror `fontSize`**: `size-[1em]`, `size-[0.875em]` to match surrounding text
+- **Custom (avoid)**: `size-[50px]` for specific dimensions
+
+```tsx
+<Heart className="size-6" />
+```
+
+### Coloring
+
+- **Stroke color**: Follows `currentColor`, use `text-*` classes (e.g., `text-primary`, `text-accent-a`)
+- **Fill**: Avoid using in most cases to maintain consistent theming
 
 ```tsx
-import { CircleHelp } from "lucide-react"
+<Heart className="text-primary" />
+```
+
+### Stroke Properties
+
+- **`strokeWidth`**: example: `stroke-[3]` (use Tailwind classes),
+- **`strokeLinecap`/`strokeLinejoin`**: Use props directly on the icon component
+
+  ```tsx
+  import { Check } from "lucide-react"
+  ;<Check
+    className="stroke-[4.5]"
+    strokeLinecap="square"
+    strokeLinejoin="miter"
+  />
+  ```
 
-// Use tailwind classes to style, using fontSize for sizing
-;<CircleHelp className="text-2xl" /> // 24px size
+  Options:
+  - `strokeLinecap`: `butt`, `round`, `square`
+  - `strokeLinejoin`: `round`, `bevel`, `miter`, `
+
+### Background Circles
+
+Wrap icon in a div for circular backgrounds, and color using background:
+
+```tsx
+<div className="bg-primary/10 grid size-10 place-items-center rounded-full">
+  <Heart className="text-primary size-5" />
+</div>
 ```
 
+### Repository Preferences
+
+1. **Preferred**: Lucide out-of-box with color styling
+2. **Acceptable**: Lucide with stroke property adjustments
+3. **Last resort**: Custom `.svg` imports
+
 ## Using custom `Image` component
 
 [Next Image](https://nextjs.org/docs/pages/api-reference/components/image) is the component of choice to handle responsive images. However, we use a custom version of this component that is properly optimized with Chakra. This way we can use style props from Chakra but still be able to forward common or Next Image-specific props to the component for correct usage and rendering.