# Icons & Images

## Icons & Images

**Folders:** `src/assets/images/`, `public/` · **Skill level:** Beginner

### Icons
Wherever a content file has an `icon:` field (services, buttons, and the icon rows of some sections, such as steps and tools), you can write any icon name from [Lucide](https://lucide.dev/icons/), a free icon set:

```yaml
icon: "PenTool"
icon: "Camera"
```

<Steps>

1. Find an icon on [lucide.dev/icons](https://lucide.dev/icons/).
2. Copy its name. The name as written on the Lucide site (`pen-tool`) works, and so does the form the theme files use (`"PenTool"`).
3. Paste it as the `icon` value.

</Steps>

Every Lucide icon is drawn as inline SVG when the site is built (`src/lib/lucideIcons.ts`), so icons load with the page and follow the text colour. A name that Lucide doesn't know draws no icon, so check new icons on the page.

An `icon` value that contains a `/` or a `.` is read as an image path instead, for example `icon: "/images/icons/my-mark.svg"` for a file in `src/assets/images/icons/`. Use it for your own SVG marks.

On Arabic pages, arrows and chevrons that point along the reading direction are mirrored for you. See [RTL & Arabic](/margo/features/rtl-arabic/).

<Aside type="tip" title="For developers">
  In components, use `<DynamicIcon name="PenTool" class="size-5" />`
  (`src/layouts/helpers/DynamicIcon.astro`), which takes a Lucide name or an
  image path, or `<Icons icon="PenTool" />` (`src/layouts/helpers/Icons.astro`)
  for Lucide only. Adding a name to `src/lib/iconNames.ts` gives editor
  autocomplete; it is optional.
</Aside>

### Where Images Live
| Folder | What goes there | How to write the path |
| --- | --- | --- |
| `src/assets/images/` | Every image in the content: projects, photo series, services, people, journal, client logos | `"/images/services/brand-identity.jpg"` for `src/assets/images/services/brand-identity.jpg` |
| `public/images/` | Files served as they are: the favicons and the fallback social image `og-image.jpg` | `/images/og-image.jpg` |
| `public/videos/` | Self-hosted videos | `/videos/my-video.mp4` |

Images in `src/assets/images/` are optimized when the site is built: resized for each screen, converted to modern formats, and lazy-loaded. Put your photos there unless a setting says `public/`.

The sample images are grouped in these folders of `src/assets/images/`:

| Folder | Used by |
| --- | --- |
| `projects/<project>/` | One folder per case study: `cover.jpg` and `gallery-1.jpg`, `gallery-2.jpg`, ... |
| `series/<series>/` | One folder per photo series, the same way |
| `services/` | The cover of each service |
| `people/` | Team members, clients in testimonials, and the portraits on the homepages |
| `blog/` | Journal post images |
| `home/`, `about/` | Homepage and about page photos |
| `logos/` | Client logos (SVG) |
| `icons/` | Social and other small icons |

A project's `image` is its cover, used on the project page, on the project cards, and in the homepage hero. Keep it 4:3, like the samples.

### Replace A Sample Photo
<Steps>

1. Put your photo in the matching folder of `src/assets/images/`, for example `src/assets/images/projects/my-project/cover.jpg`. A large JPG (about 2000 px wide) is fine: the build makes the smaller sizes.

2. In the content file that uses the old photo, change the path and describe the new photo:

   ```yaml
   image: "/images/projects/my-project/cover.jpg"
   imageAlt: "A stack of printed packaging samples on a grey table"
   ```

3. Make the same change in the same file in `french/` and `arabic/`, with the alt text in that language.

</Steps>

Or keep the file name and replace the file itself: every page that uses it changes at once. To find which file uses a photo, search the project for its file name, for example `cover.jpg` inside the project's folder name.

### Alt Text
Every image field has a matching alt field: `imageAlt` on projects and services, `alt` on each block of a project's `images` list, and `alt` in the section files. Screen readers read it, and search engines use it.

- Describe what the image shows, in one short sentence: "A stack of printed packaging samples on a grey table".
- Don't start with "Image of", and don't repeat the caption.
- Leave it empty (`""`) only for a purely decorative image.

### Dark Mode Images
A page's `image` can have a dark mode version in `imageDark`. In components, `OptimizedImage` takes `darkSrc` for the same purpose (`src/layouts/components/utilities/OptimizedImage.astro`).

### Videos
A project page can show a video as one of its `images` blocks: `type: "video"`, `src` (a file in `public/videos/` or a video URL), `alt`, and an optional `poster` image shown before it plays. See [Projects](/margo/customization/projects/).

### Social Icons
The social links in `src/config/social.json` each have an `icon` (an SVG in `src/assets/images/icons/`, such as `/images/icons/instagram.svg`) and a `url`. Replace each `url` with your own profile, and set `"enable": false` on the networks you don't use. Search engines also read these links as your profiles (see [SEO & AI Visibility](/margo/customization/seo-ai-visibility/)).

<Aside type="note">
  The logo and favicons are covered in [Site Identity & Logo](/margo/customization/site-identity-logo/).
  The social preview image is in [SEO & AI Visibility](/margo/customization/seo-ai-visibility/).
  Replace every sample photo, portrait, and client logo with your own before you launch.
</Aside>

### Do It With AI
```text
I added my photos to src/assets/images/[FOLDER]/: [LIST FILES AND WHAT EACH SHOWS]. Replace the
sample photos with them in the matching content files (english, french, and arabic folders):
change the image path and write a short, specific alt text in each language. Keep the 4:3 shape
for project covers, and tell me which sample photos are still in use.
```