diff --git a/README.md b/README.md
index 8a16c74..f6e6daa 100644
--- a/README.md
+++ b/README.md
@@ -20,9 +20,14 @@ Create badges from objects or as standalone elements.
 
 Any object that you would like to be able to be turned into a badge must implement `BadgeableInterface`.
 
-This interface specifies a single method `getBadgeColour()` which expects an instance of the enum `BadgeColour` to be returned and is used to determine the colour of the rendered badge.
+You can use `BadgeableTrait` to get a default implementation.
 
-This method can contain as much logic in it as you'd like to return different colours of badge under different circumstances. EG:
+The interface specifies two methods:
+
+- `getBadgeColour(): BadgeColour` — returns the enum case that determines the badge's colour.
+- `getBadgeIcon(): ?string` — returns an [Iconify](https://iconify.design) icon name (e.g. `material-symbols:add-alert`), or `null` for no icon.
+
+Either method can contain as much logic as you like:
 
 ```php
 // Job.php
@@ -37,6 +42,11 @@ public function getBadgeColour(): BadgeColour
         default                => BadgeColour::GREY
     };
 }
+
+public function getBadgeIcon(): ?string
+{
+    return null;
+}
 ```
 
 You then specify the object using the `:obj` prop when rendering the badge:
@@ -47,6 +57,26 @@ You then specify the object using the `:obj` prop when rendering the badge:
 <twig:Pcm:Badge :obj="job">{{ job.kind.value }}</twig:Pcm:Badge>
 ```
 
+## Using `BadgeableTrait`
+
+If you only care about one of the interface methods, use `BadgeableTrait` for sensible defaults (`BadgeColour::DEFAULT` and no icon) and override only what you need:
+
+```php
+use Pcm\BadgeBundle\Interface\BadgeableInterface;
+use Pcm\BadgeBundle\Trait\BadgeableTrait;
+
+class Job implements BadgeableInterface
+{
+    use BadgeableTrait;
+
+    public function getBadgeColour(): BadgeColour
+    {
+        return BadgeColour::BLUE;
+    }
+    // getBadgeIcon() inherited from the trait — returns null
+}
+```
+
 <br>
 
 # Standalone badges
@@ -70,10 +100,14 @@ A badge must contain either an `obj` or a `colour`, but not both.
 obj="{{ job.kind }}"
 ```
 
-`colour` - One of the available colours specified by the `Badge` enum. For a full list of acceptable values type in some junk and read the exception message.
+`colour` - One of the available colours specified by the `BadgeColour` enum. The palette covers the usual primaries plus tones like `cyan`, `indigo`, `purple`, `slate`, `stone`, `teal` and `violet` — see `src/Enum/BadgeColour.php` for the full list, or pass an invalid value and read the exception message.
 
 `outline` - A boolean attribute that changes the style of the badge to an outline.
 
+`glossy` - A boolean attribute that adds a subtle gradient highlight to the badge. Works with both solid and outline variants; solid badges get a white-tinted radial sheen, outlined badges get a faint colour-tinted version.
+
+`icon` - Render an icon to the left of the label. Pass an [Iconify](https://iconify.design) name (e.g. `icon="material-symbols:add-alert"`) to use a specific icon, or pass it as a boolean (`icon`) when using `:obj` to use the icon returned by `getBadgeIcon()`. Requires `symfony/ux-icons` in the host project.
+
 `class` - Extra classes you want to add to the badge element. These are merged with the badge base classes taking priority in case of conflicts.
 
 `label` - Badge label text. Content inside the content block will be prioritised over the label attribute if present.
@@ -96,16 +130,14 @@ pcm_badge:
 
 <br>
 
-# Development
+# Local development
 
-In the host project, require the bundle pinned to the `develop` branch:
+The bundle ships with a small Symfony preview app under `dev/` that renders many different badge variants.
 
 ```bash
-composer require pcm/badge-bundle:dev-develop
+just composer_install   # install dependencies
+just serve              # start the preview at http://localhost:8000
 ```
 
-The `dev-` prefix tells Composer to install from a branch rather than a tagged version. Each time you push a new commit to `develop`, run the following in the host project to pull it in:
+Edit `dev/templates/showcase.html.twig` to add or tweak variants — changes are picked up on refresh. Other handy recipes (see `justfile`):
 
-```bash
-composer update pcm/badge-bundle
-```