diff --git a/README.md b/README.md
index ee4f01f5..f06ce01a 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ Material 3 Expressive components for Laravel and Livewire, built on Tailwind CSS
 - A colour scheme generated from one seed colour with Google's colour science (`php artisan material:scheme`), light and dark, and a theme that is chosen before the first paint.
 - The full Material Symbols Rounded set and the M3 Expressive shapes, drawn inline without an icon package.
 - Error pages and a Markdown mail theme in the same scheme.
-- A showcase of every component in the application's own scheme, a design guard for tests, and Laravel Boost guidelines and a skill for AI agents.
+- A showcase of every component in the application's own scheme, a design guard for tests, and for AI agents two Laravel Boost guidelines and two skills: the library's own, and Material 3's rules and tables beside its utilities.
 
 No JavaScript libraries beyond the Alpine that ships with Livewire. Browsers: Chrome 125+, Firefox 147+, Safari 18.4+.
 
@@ -156,7 +156,7 @@ Two checks are opt-in: `forbidAbsolutes()` also fails on `bg-white` and `text-bl
 
 ## AI agents
 
-With [Laravel Boost](https://github.com/laravel/boost), `php artisan boost:install` (or `boost:update --discover`) picks up the package's guideline and the `livewire-material-development` skill.
+With [Laravel Boost](https://github.com/laravel/boost), `php artisan boost:install` (or `boost:update --discover`) picks up the package's two guidelines — the library's own, and `material-3`, a page of M3's rules an agent reads in every session — and two skills: `livewire-material-development` (every component, prop, slot and trap) and `material-3-design` (M3's colour roles, surfaces, elevation, shape, type, motion, states, window size classes and accessibility, with the library's utility beside each M3 name and Google's source page for each chapter).
 
 ## Developing the package
 
diff --git a/resources/views/showcase/sections/colour.blade.php b/resources/views/showcase/sections/colour.blade.php
index 6fa70d5c..c240d608 100644
--- a/resources/views/showcase/sections/colour.blade.php
+++ b/resources/views/showcase/sections/colour.blade.php
@@ -37,6 +37,10 @@
         <code>php artisan material:scheme</code>. Both themes side by side, whatever the page is showing.
     </p>
 
+    <p class="max-w-3xl type-body-md text-on-surface-variant" data-test="when-to-use">
+        When to use which: <code>primary</code> is the one key action on a screen; <code>secondary-container</code> is the quiet fill (tonal buttons, selected navigation and chips); <code>tertiary</code> is a rare accent; <code>error</code>, <code>success</code>, <code>warning</code> and <code>info</code> mean state — the <code>-container</code> for a tinted panel, the role itself for its text and icon. Pair a role only with its <code>on-</code> partner. Ink is <code>on-surface</code>, lower emphasis <code>on-surface-variant</code>, decoration <code>outline</code>; never an opacity, because 38% means disabled. Every role changes with the contrast level below, which is why only roles are allowed.
+    </p>
+
     <p class="max-w-3xl type-body-md text-on-surface-variant">
         With colour profiles in <code>livewire-material.profiles</code>, the command generates each one under
         <code>&lt;html data-scheme&gt;</code>, and <code>&lt;x-scheme-picker&gt;</code> chooses between them. Without
diff --git a/resources/views/showcase/sections/elevation.blade.php b/resources/views/showcase/sections/elevation.blade.php
index ae4fca64..bcde41f5 100644
--- a/resources/views/showcase/sections/elevation.blade.php
+++ b/resources/views/showcase/sections/elevation.blade.php
@@ -5,6 +5,10 @@
         Five shadow levels as <code>shadow-elevation-*</code>, for what floats over content.
     </p>
 
+    <p class="max-w-3xl type-body-md text-on-surface-variant" data-test="when-to-use">
+        Panels separate by tone first: the <code>surface-container</code> steps are a hierarchy of emphasis, not of height. Shadows are for what floats or lifts — 1 for elevated cards, buttons and modal sheets; 2 for menus, the navigation bar and a scrolled app bar; 3 for the FAB, dialogs, pickers and search; one level more on hover; nothing rests above 3. Fewer shadows carry more meaning.
+    </p>
+
     <div class="grid grid-cols-2 gap-6 rounded-corner-lg bg-surface-container-low p-6 medium:grid-cols-5">
         @foreach (['shadow-elevation-1', 'shadow-elevation-2', 'shadow-elevation-3', 'shadow-elevation-4', 'shadow-elevation-5'] as $shadow)
             <div @class(['flex h-24 items-center justify-center rounded-corner-md bg-surface-container-high', $shadow])>
diff --git a/resources/views/showcase/sections/icons.blade.php b/resources/views/showcase/sections/icons.blade.php
index aa7c51ed..bba669a6 100644
--- a/resources/views/showcase/sections/icons.blade.php
+++ b/resources/views/showcase/sections/icons.blade.php
@@ -25,6 +25,10 @@
         the 20 cut: <code>&lt;x-icon name="…" optical="20" class="size-5" /&gt;</code>.
     </p>
 
+    <p class="max-w-3xl type-body-md text-on-surface-variant" data-test="when-to-use">
+        <code>filled</code> means active or selected; <code>optical="20"</code> when an icon is drawn at 20px or less; one weight per group. An icon takes the size and colour of the text beside it. An icon-only control carries an accessible name; a decorative icon is hidden.
+    </p>
+
     <div class="flex flex-wrap items-center gap-4">
         <label class="flex min-w-72 flex-1 items-center gap-2 rounded-corner-xs border border-outline px-3 py-2 focus-within:outline-3 focus-within:outline-secondary">
             <x-livewire-material::icon name="search" class="size-5 text-on-surface-variant" />
diff --git a/resources/views/showcase/sections/motion.blade.php b/resources/views/showcase/sections/motion.blade.php
index 6ebe3e87..aafc9244 100644
--- a/resources/views/showcase/sections/motion.blade.php
+++ b/resources/views/showcase/sections/motion.blade.php
@@ -6,6 +6,10 @@
         <code>--md-sys-motion-*-duration</code>. Reduced motion makes all of them instant.
     </p>
 
+    <p class="max-w-3xl type-body-md text-on-surface-variant" data-test="when-to-use">
+        Position, size and shape move on the spatial springs, which overshoot — <code>fast</code> for small elements, <code>slow</code> for large ones. Colour and opacity move on the effects springs, which never overshoot. Always pair an easing with its duration; everything that moves goes through these tokens, so reduced motion makes it instant. The Standard scheme (<code>motion.scheme</code>) swaps the spatial springs for a restrained set.
+    </p>
+
     <button type="button" class="state-layer focus-ring rounded-corner-full bg-primary px-6 py-2.5 type-label-lg text-on-primary" x-on:click="moved = ! moved">
         Move
     </button>
diff --git a/resources/views/showcase/sections/shape.blade.php b/resources/views/showcase/sections/shape.blade.php
index d07062a0..7c84d960 100644
--- a/resources/views/showcase/sections/shape.blade.php
+++ b/resources/views/showcase/sections/shape.blade.php
@@ -5,6 +5,10 @@
         The corner scale as <code>rounded-corner-*</code>, and M3 Expressive's shapes as <code>&lt;x-shape name="…" /&gt;</code>.
     </p>
 
+    <p class="max-w-3xl type-body-md text-on-surface-variant" data-test="when-to-use">
+        When to use which: <code>full</code> for buttons, icon buttons, chips' avatars, badges, switches, sliders, the search bar and navigation indicators; <code>xs</code> for text fields, menus, snackbars and plain tooltips; <code>sm</code> for chips; <code>md</code> for cards and rich tooltips; <code>lg</code> for the FAB and a side sheet's inner corners; <code>xl</code> for dialogs, bottom sheets, pickers and carousel items; <code>xxl</code> for hero containers. A nested corner is the outer radius minus the padding. A press squares a round shape; nothing morphs on hover. The shapes below are decoration, never meaning.
+    </p>
+
     <div class="grid grid-cols-2 gap-4 medium:grid-cols-5">
         @foreach (['rounded-corner-none', 'rounded-corner-xs', 'rounded-corner-sm', 'rounded-corner-md', 'rounded-corner-lg', 'rounded-corner-lg-increased', 'rounded-corner-xl', 'rounded-corner-xl-increased', 'rounded-corner-xxl', 'rounded-corner-full'] as $corner)
             <div class="space-y-2">
diff --git a/resources/views/showcase/sections/type.blade.php b/resources/views/showcase/sections/type.blade.php
index d2a7b8e9..d6707af3 100644
--- a/resources/views/showcase/sections/type.blade.php
+++ b/resources/views/showcase/sections/type.blade.php
@@ -25,6 +25,10 @@
         M3's typescale in Google Sans Flex, each style regular and emphasized: <code>type-title-lg</code>, <code>type-emphasized-title-lg</code>.
     </p>
 
+    <p class="max-w-3xl type-body-md text-on-surface-variant" data-test="when-to-use">
+        When to use which: <code>display</code> for hero figures and short marketing lines; <code>headline</code> for page and section titles; <code>title</code> for card, dialog and list-section titles; <code>body</code> for paragraphs (<code>body-lg</code> for reading); <code>label</code> inside components. The emphasized styles are opt-in — a selected item, a primary action, a headline — not decoration. Keep 40–60 characters per line and <code>tabular-nums</code> on figures that change.
+    </p>
+
     <div class="divide-y divide-divider rounded-corner-lg bg-surface-container">
         @foreach ($styles as [$regular, $emphasized])
             <div class="grid gap-2 p-4 expanded:grid-cols-[12rem_1fr_1fr] expanded:items-baseline">