From 4e843bcf9a246757a5469eaa75b49b0fe652eae5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dante=20=C3=81lvarez?=
 <89805481+danalvrz@users.noreply.github.com>
Date: Tue, 7 Oct 2025 18:40:10 -0600
Subject: [PATCH 01/10] add updated sections

---
 .../advanced-components-bm3.md                | 726 ++++++++++++++++++
 .../block-development-widgets.md              | 647 ++++++++++++++++
 .../customizing-volto-light-theme/concepts.md | 249 +++++-
 .../creating-new-project.md                   |  11 -
 .../design-system-implementation.md           | 453 +++++++++++
 docs/customizing-volto-light-theme/index.md   |   7 +-
 .../installing-vlt.md                         |  71 --
 .../integrate-new-block.md                    |  44 --
 docs/customizing-volto-light-theme/theming.md | 342 ---------
 9 files changed, 2042 insertions(+), 508 deletions(-)
 create mode 100644 docs/customizing-volto-light-theme/advanced-components-bm3.md
 create mode 100644 docs/customizing-volto-light-theme/block-development-widgets.md
 delete mode 100644 docs/customizing-volto-light-theme/creating-new-project.md
 create mode 100644 docs/customizing-volto-light-theme/design-system-implementation.md
 delete mode 100644 docs/customizing-volto-light-theme/installing-vlt.md
 delete mode 100644 docs/customizing-volto-light-theme/integrate-new-block.md
 delete mode 100644 docs/customizing-volto-light-theme/theming.md

diff --git a/docs/customizing-volto-light-theme/advanced-components-bm3.md b/docs/customizing-volto-light-theme/advanced-components-bm3.md
new file mode 100644
index 000000000..b90172a9d
--- /dev/null
+++ b/docs/customizing-volto-light-theme/advanced-components-bm3.md
@@ -0,0 +1,726 @@
+---
+myst:
+  html_meta:
+    "description": "Advanced Components, Site Customization & Block Model v3"
+    "property=og:description": "Advanced Components, Site Customization & Block Model v3"
+    "property=og:title": "Advanced Components, Site Customization & Block Model v3"
+    "keywords": "Plone, Volto, Training, Volto Light Theme, Integrate, block"
+---
+
+# 4. Advanced Components, Site Customization & Block Model v3
+
+## 4.1 Understanding the Card Primitive
+
+The Card primitive is VLT's reusable component for displaying content in card layouts. It has three configurable slots: image, summary, and actions.
+
+### Card Structure
+
+```jsx
+<Card href="/path/to/item">
+  <Card.Image src="/path/to/image" />
+  <Card.Summary>
+    <h2>Title</h2>
+    <p>Summary text goes here.</p>
+  </Card.Summary>
+  <Card.Actions>
+    <Button>Action 1</Button>
+  </Card.Actions>
+</Card>
+```
+
+### Card Variations
+
+- **Vertical layout** (default): Image on top
+- **Horizontal layout**: Image on left or right
+- **Contained**: With background color from theme
+- **Listing**: Image displayed on left with specific size (controlled by `--card-listing-image-size`, default 220px)
+
+### Card.Image Slot
+
+Display an image using a `src` prop or use a Plone image object:
+
+```tsx
+<Card.Image image={image} />
+```
+
+Custom image component:
+
+```tsx
+<Card.Image
+  src="/path/to/image"
+  imageComponent={MyCustomImageComponent}
+/>
+```
+
+### Card.Summary Slot
+
+Recommended structure using VLT's Summary component:
+
+```tsx
+import DefaultSummary from '@kitconcept/volto-light-theme/components/Summary/DefaultSummary';
+
+const Summary = config.getComponent({
+  name: 'Summary',
+  dependencies: [item['@type']],
+}).component || DefaultSummary;
+
+<Card.Summary>
+  <Summary item={item} HeadingTag="h2" />
+</Card.Summary>
+```
+
+## 4.2 Creating Custom Summary Components
+
+The Summary component displays content metadata in listings, teasers, and cards. VLT includes built-in implementations:
+
+- `DefaultSummary`: Kicker, title, and description
+- `NewsItemSummary`: Publication date, kicker, title, description
+- `EventSummary`: Start/end date, kicker, title, description
+- `FileSummary`: File size and type
+
+### Step 1: Create Product Content Type
+
+First, create a custom "Product" content type through the Plone UI:
+
+1. Go to http://localhost:3000/controlpanel/dexterity-types
+2. Click "Add New Content Type"
+3. Fill in:
+   - **Type Name**: Product
+   - **Short Name**: product (auto-filled)
+   - **Description**: A product with pricing information
+4. Click "Add"
+5. In the "Behaviors" tab, enable:
+   - "Kicker" (we'll use this field to store the price)
+   - "Preview image"
+   - Any other desired behaviors (Dublin Core, etc.)
+6. Click "Save"
+
+### Step 2: Create a Custom Summary Component
+
+Create `src/components/Summary/ProductSummary.jsx`:
+
+```jsx
+import { FormattedNumber } from 'react-intl';
+
+const ProductSummary = ({ item, HeadingTag = 'h3' }) => {
+  const { title, description, head_title, currency = 'EUR' } = item;
+  const price = parseFloat(head_title);
+
+  return (
+    <>
+      <HeadingTag className="product-title">
+        {title ? title : item.id}
+      </HeadingTag>
+      {description && <p className="product-description">{description}</p>}
+      {head_title && !isNaN(price) && (
+        <div className="product-price">
+          <span className="price">
+            <FormattedNumber
+              value={price}
+              style="currency"
+              currency={currency}
+            />
+          </span>
+        </div>
+      )}
+    </>
+  );
+};
+
+ProductSummary.hideLink = false;
+export default ProductSummary;
+```
+
+**Note**: We use the `head_title` field (kicker) to store price information. The price is formatted using `FormattedNumber` for proper currency display with EUR as default. In a real project, you would create custom fields for price and currency.
+
+### Step 3: Add Styles for Product Summary
+
+Create `src/theme/_productSummary.scss`:
+
+```scss
+.products .card .card-summary {
+  padding-bottom: 0 !important;
+  .product-price {
+    font-size: 1.25rem;
+    font-weight: var(--font-bold);
+    color: var(--accent-color);
+    margin-bottom: 0.5rem;
+    margin-top: 0.5rem;
+
+    .price {
+      background: var(--theme-high-contrast-color);
+      padding: 0.25rem 0.75rem;
+      border-radius: 4px;
+    }
+  }
+
+  .product-title {
+    margin-top: 0;
+  }
+}
+```
+
+Import in `src/theme/_main.scss`:
+
+```scss
+@import './blocks/hero';
+@import './blocks/relatedItems';
+@import './productSummary';
+@import './site';
+```
+
+### Step 4: Register the Summary Component
+
+In `src/config/settings.ts`:
+
+```typescript
+import ProductSummary from '../components/Summary/ProductSummary';
+
+export default function install(config: ConfigType) {
+  // ... previous config ...
+
+  config.registerComponent({
+    name: 'Summary',
+    component: ProductSummary,
+    dependencies: ['product'],
+  });
+
+  return config;
+}
+```
+
+### Step 5: Test the Product Summary
+
+1. Create a Product item in your site
+2. Fill in the title, description, and kicker field (e.g., "$99.99")
+3. Add the Product to a Listing or Teaser block
+4. The custom ProductSummary will display the price, title, and description
+
+## 4.3 Creating Custom Listing Variations with Card Actions
+
+Listing variations customize content display in Listing blocks. Let's create a ProductTemplate demonstrating the Card.Actions slot for interactive buttons.
+
+### Card.Actions Slot
+
+The Card.Actions slot provides interactive elements beyond the main card link:
+- "Add to Cart" or "Get Now" buttons for products
+- "Download" buttons for files
+- "Register" buttons for events
+
+### Step 1: Create ProductActions Component
+
+Create `src/components/Actions/ProductAction.jsx`:
+
+```jsx
+const ProductActions = ({ item }) => {
+  return (
+    <>
+      <button className="rent-now-button button">Rent now</button>
+    </>
+  );
+};
+
+export default ProductActions;
+```
+
+### Step 2: Register ProductActions
+
+Update `src/config/settings.ts`:
+
+```typescript
+import ProductActions from '../components/Actions/ProductAction';
+
+export default function install(config: ConfigType) {
+  // ... previous configuration ...
+
+  // Register ProductActions component
+  config.registerComponent({
+    name: 'Actions',
+    component: ProductActions,
+    dependencies: ['product'],
+  });
+
+  return config;
+}
+```
+
+### Step 3: Create ProductTemplate Listing Variation
+
+Create `src/components/blocks/Listing/ProductTemplate.jsx`:
+
+```jsx
+import React from 'react';
+import PropTypes from 'prop-types';
+import ConditionalLink from '@plone/volto/components/manage/ConditionalLink/ConditionalLink';
+import Card from '@kitconcept/volto-light-theme/primitives/Card/Card';
+import { flattenToAppURL, isInternalURL } from '@plone/volto/helpers/Url/Url';
+import config from '@plone/volto/registry';
+import DefaultSummary from '@kitconcept/volto-light-theme/components/Summary/DefaultSummary';
+import cx from 'classnames';
+
+const ProductTemplate = ({ items, linkTitle, linkHref, isEditMode }) => {
+  let link = null;
+  let href = linkHref?.[0]?.['@id'] || '';
+  const PreviewImageComponent = config.getComponent('PreviewImage').component;
+
+  if (isInternalURL(href)) {
+    link = (
+      <ConditionalLink to={flattenToAppURL(href)} condition={!isEditMode}>
+        {linkTitle || href}
+      </ConditionalLink>
+    );
+  } else if (href) {
+    link = <a href={href}>{linkTitle || href}</a>;
+  }
+
+  return (
+    <>
+      <div className="items">
+        {items.map((item) => {
+          const Summary =
+            config.getComponent({
+              name: 'Summary',
+              dependencies: [item['@type']],
+            }).component || DefaultSummary;
+
+          const Actions = config.getComponent({
+            name: 'Actions',
+            dependencies: [item['@type']],
+          }).component;
+
+          const showLink = !Summary.hideLink && !isEditMode;
+
+          return (
+            <div
+              className={cx('listing-item', {
+                [`${item['@type']?.toLowerCase()}-listing`]: item['@type'],
+              })}
+              key={item['@id']}
+            >
+              <Card href={showLink ? item['@id'] : null}>
+                {item.image_field !== '' && (
+                  <Card.Image
+                    className="item-image"
+                    item={item}
+                    imageComponent={PreviewImageComponent}
+                  />
+                )}
+                <Card.Summary>
+                  <Summary item={item} HeadingTag="h2" />
+                </Card.Summary>
+                <Card.Actions>
+                  {Actions && <Actions item={item} />}
+                </Card.Actions>
+              </Card>
+            </div>
+          );
+        })}
+      </div>
+
+      {link && <div className="footer">{link}</div>}
+    </>
+  );
+};
+
+ProductTemplate.propTypes = {
+  items: PropTypes.arrayOf(PropTypes.any).isRequired,
+  linkTitle: PropTypes.string,
+  linkHref: PropTypes.any,
+  isEditMode: PropTypes.bool,
+};
+
+export default ProductTemplate;
+```
+
+**Key Features:**
+- Uses `config.getComponent()` to fetch registered Summary/Actions components by content type
+- `showLink` ensures cards are only clickable when appropriate
+- `isEditMode` disables navigation during editing
+- Dynamically renders Actions only for content types that have them registered
+
+### Step 4: Register ProductTemplate
+
+Update `src/config/blocks.ts`:
+
+```typescript
+import ProductTemplate from '../components/blocks/Listing/ProductTemplate';
+
+export default function install(config: ConfigType) {
+  // ... previous configuration ...
+
+  // Register ProductTemplate listing variation
+  config.blocks.blocksConfig.listing.variations = [
+    ...(config.blocks.blocksConfig.listing.variations || []),
+    {
+      id: 'products',
+      title: 'Products',
+      template: ProductTemplate,
+    },
+  ];
+
+  return config;
+}
+```
+
+### Step 5: Add Styles
+
+Create `src/theme/blocks/_listing.scss`:
+
+```scss
+.block.listing {
+  &.products {
+    .items {
+      display: grid;
+      grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+      gap: 2rem;
+
+      .card {
+        .card-actions {
+          padding: 1rem;
+          border-top: 1px solid var(--theme-high-contrast-color);
+
+          .add-to-cart {
+            width: 100%;
+            padding: 0.75rem 1rem;
+            background-color: var(--accent-color);
+            color: var(--accent-foreground-color);
+            border: none;
+            border-radius: 4px;
+            font-weight: var(--font-bold);
+            cursor: pointer;
+            transition: opacity 0.2s;
+
+            &:hover {
+              opacity: 0.9;
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Import in `src/theme/_main.scss`:
+
+```scss
+@import './blocks/hero';
+@import './blocks/relatedItems';
+@import './blocks/listing';
+@import './productSummary';
+@import './site';
+```
+
+### Step 6: Test the Product Listing
+
+1. Create Product items with title, description, kicker (price), and images
+2. Add a Listing block to a page
+3. Select "Products" variation in block settings
+4. Configure to show Product content type
+5. Products display with image, summary, and "Get now" button
+
+## 4.4 Working with Slots
+
+VLT provides slots for extending the layout without component shadowing. Let's create a practical example: a newsletter signup component in the preFooter slot.
+
+### Available Slots
+
+- `aboveHeader`: Content above header
+- `belowHeader`: Content below header
+- `headerTools`: Header tools at top-right (includes Anontools by default)
+- `preFooter`: Before footer
+- `postFooter`: After footer
+- `footer`: Main footer area
+- `footerLinks`: Footer links section
+- `followUs`: Social media section
+
+### Step 1: Create Newsletter Signup Component
+
+Create `src/components/NewsletterSignup/NewsletterSignup.jsx`:
+
+```jsx
+import React, { useState } from 'react';
+
+const NewsletterSignup = () => {
+  const [email, setEmail] = useState('');
+
+  const handleSubmit = (e) => {
+    e.preventDefault();
+    // In a real implementation, this would submit to a newsletter service
+    console.log('Newsletter signup:', email);
+    alert(`Thanks for signing up with ${email}!`);
+    setEmail('');
+  };
+
+  return (
+    <div className="newsletter-signup">
+      <div className="newsletter-container">
+        <h2 className="newsletter-title">Stay Updated</h2>
+        <p className="newsletter-description">
+          Subscribe to our newsletter for the latest updates and news.
+        </p>
+        <form onSubmit={handleSubmit} className="newsletter-form">
+          <input
+            type="email"
+            value={email}
+            onChange={(e) => setEmail(e.target.value)}
+            placeholder="Enter your email"
+            required
+            className="newsletter-input"
+          />
+          <button type="submit" className="newsletter-button">
+            Subscribe
+          </button>
+        </form>
+      </div>
+    </div>
+  );
+};
+
+export default NewsletterSignup;
+```
+
+### Step 2: Add Styles
+
+Create `src/theme/_newsletterSignup.scss`:
+
+```scss
+.newsletter-signup {
+  background-color: var(--secondary-color);
+  color: var(--secondary-foreground-color);
+  padding: 4rem 2rem;
+
+  .newsletter-container {
+    max-width: var(--default-container-width);
+    margin: 0 auto;
+    text-align: center;
+  }
+
+  .newsletter-title {
+    font-size: 2rem;
+    margin-bottom: 1rem;
+    font-weight: var(--font-bold);
+  }
+
+  .newsletter-description {
+    font-size: 1.125rem;
+    margin-bottom: 2rem;
+    opacity: 0.9;
+  }
+
+  .newsletter-form {
+    display: flex;
+    gap: 1rem;
+    max-width: 500px;
+    margin: 0 auto;
+    flex-wrap: wrap;
+    justify-content: center;
+
+    .newsletter-input {
+      flex: 1;
+      min-width: 250px;
+      padding: 0.75rem 1rem;
+      border: 1px solid var(--secondary-foreground-color);
+      font-size: 1rem;
+      background-color: var(--primary-color);
+      color: var(--primary-foreground-color);
+
+      &:focus {
+        outline: 2px solid var(--accent-color);
+        outline-offset: 2px;
+      }
+    }
+
+    .newsletter-button {
+      padding: 0.75rem 2rem;
+      background-color: var(--accent-color);
+      color: var(--accent-foreground-color);
+      border: none;
+      font-size: 1rem;
+      font-weight: var(--font-bold);
+      cursor: pointer;
+      transition: opacity 0.2s;
+
+      &:hover {
+        opacity: 0.9;
+      }
+
+      &:focus {
+        outline: 2px solid var(--accent-foreground-color);
+        outline-offset: 2px;
+      }
+    }
+  }
+}
+```
+
+Import in `src/theme/_main.scss`:
+
+```scss
+@import './blocks/hero';
+@import './blocks/relatedItems';
+@import './blocks/listing';
+@import './productSummary';
+@import './site';
+@import './newsletterSignup';
+```
+
+### Step 3: Register the Component to the Slot
+
+In `src/config/settings.ts`:
+
+```typescript
+import NewsletterSignup from '../components/NewsletterSignup/NewsletterSignup';
+
+export default function install(config: ConfigType) {
+  // ... previous config ...
+
+  config.registerSlotComponent({
+    name: 'NewsletterSignup',
+    slot: 'preFooter',
+    component: NewsletterSignup,
+  });
+
+  return config;
+}
+```
+
+The newsletter signup component will now appear before the footer on all pages, demonstrating how slots enable you to extend the layout without shadowing core components.
+
+## 4.5 Site Customization Behaviors
+
+VLT provides backend behaviors for site customization that you activated earlier. These behaviors enable fields for customizing the site without code changes.
+
+### Header Customization Options
+
+Through the Plone UI, you can customize:
+- **Site logo**: Main logo in the top left
+- **Complementary logo**: Second logo on the right side
+- **Fat menu**: Enabled by default, can be disabled
+- **Intranet header**: Alternative header for intranet sites
+- **Actions**: Links at the top right
+
+### Theme Customization Options
+
+- Navigation text color
+- Fat menu and breadcrumbs text color
+- Fat menu background color
+- Footer font color
+- Footer background color
+
+### Footer Customization Options
+
+- **Footer links**: Additional links with title, URL, and new tab option
+- **Footer logos**: List of logos with links and customizable size (small/large) and container width (default/layout)
+- **Footer colophon text**: Customizable last line of footer
+
+## 4.6 Block Model v3 (opt-in)
+
+```{note}
+Block Model v3 is a beta feature. It's recommended to only use it when all blocks in your registry are v3-compatible (indicated by banner in block's GitHub repository).
+```
+
+Block Model v3 introduces a unified container architecture that ensures consistent styling and spacing between View and Edit modes. This eliminates the previous issues where Edit mode appeared different from View mode.
+
+### Key Benefits
+
+- Consistent rendering across View and Edit modes
+- Simplified CSS with standardized container structure
+- Improved spacing control through block categories
+- Reduced maintenance overhead
+
+### The Two-Container System
+
+Every block in Block Model v3 follows this structure:
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ Main/Outer Container (.block.${type}.category-${category}) │
+│ • Full width (edge to edge)                                │
+│ • Background color & theme variables                       │
+│ • Vertical spacing via padding on BG color changes         │
+│                                                            │
+│  ┌───────────────────────────────────────────────────────┐ │
+│  │ Secondary/Inner Container (.block-inner-container)    │ │
+│  │ • Content width & horizontal centering                │ │
+│  │ • Default vertical spacing between blocks             │ │
+│  │ • Content alignment via CSS Grid                      │ │
+│  │                                                       │ │
+│  │    [Block Content Here]                               │ │
+│  │                                                       │ │
+│  └───────────────────────────────────────────────────────┘ │
+└────────────────────────────────────────────────────────────┘
+```
+
+**Main/Outer Container:**
+- Full width (extends edge to edge)
+- Handles background colors and theme variables
+- Uses padding (not margin) for vertical spacing
+- CSS Classes: `.block.${type}.category-${category}`
+
+**Secondary/Inner Container:**
+- Controls content width constraints
+- Provides consistent inter-block spacing
+- Supports content alignment through CSS Grid
+- CSS Class: `.block-inner-container`
+
+### Enable Block Model v3
+
+In your project's `src/config/settings.ts`:
+
+```typescript
+export default function install(config: ConfigType) {
+  // Enable Block Model v3 globally
+  config.settings.blockModel = 3;
+
+  // Define block categories for spacing
+  config.blocks.blocksConfig.slate.category = 'inline';
+  config.blocks.blocksConfig.title.category = 'title';
+  config.blocks.blocksConfig.__button.category = 'action';
+  config.blocks.blocksConfig.gridBlock.category = 'cards';
+
+  return config;
+}
+```
+
+### Block Categories
+
+Block categories determine spacing relationships between adjacent blocks. Categories are available at `config.blocks.blocksConfig.[$type].category`.
+
+Vertical spacing between blocks is provided by the **upper block**:
+- Block content should be flush with top of container
+- Bottom padding creates space for following block
+- Different category combinations may have specific spacing adjustments
+
+### View Mode Structure
+
+```jsx
+<div
+  style="$StyleWrapperStyles"
+  className="block $type category-$category $StyleWrapperClassNames"
+>
+  <div className="block-inner-container">
+    {View component}
+  </div>
+</div>
+```
+
+### Edit Mode Structure
+
+```jsx
+<div
+  style="$StyleWrapperStyles"
+  className="block $type category-$category $StyleWrapperClassNames"
+>
+  <div className="block-inner-container">
+    {Edit component}
+  </div>
+  <div className="block-edit-helpers">
+    {/* Delete block button, move block buttons, etc. */}
+  </div>
+</div>
+```
+
+Notice how the actual block content remains identical in both modes, while the framework containers handle all the differences in layout and editing functionality.
+
+---
diff --git a/docs/customizing-volto-light-theme/block-development-widgets.md b/docs/customizing-volto-light-theme/block-development-widgets.md
new file mode 100644
index 000000000..a363ee1fa
--- /dev/null
+++ b/docs/customizing-volto-light-theme/block-development-widgets.md
@@ -0,0 +1,647 @@
+---
+myst:
+  html_meta:
+    "description": "Block Development, Widgets & Integration"
+    "property=og:description": "Block Development, Widgets & Integration"
+    "property=og:title": "Block Development, Widgets & Integration"
+    "keywords": "Plone, Volto, Training, Volto Light Theme"
+---
+
+# 3. Block Development, Widgets & Integration
+
+## 3.1 Understanding VLT Widgets
+
+VLT provides powerful widgets for block configuration that work with the StyleWrapper system.
+
+### BlockWidth Widget
+
+Controls the content width of blocks:
+
+```javascript
+{
+  widget: 'blockWidth',
+  title: 'Block Width',
+  default: 'default',
+}
+```
+
+### BlockAlignment Widget
+
+Controls content alignment within blocks:
+
+```javascript
+{
+  widget: 'blockAlignment',
+  title: 'Alignment',
+  default: 'center',
+}
+```
+
+### ThemeColorSwatch Widget
+
+Allows selection from configured themes stored in `config.blocks.themes`:
+
+```javascript
+{
+  widget: 'themeColorSwatch',
+  title: 'Color Theme',
+  colors: config.blocks.themes,
+}
+```
+
+### ObjectList Widget
+
+Allows introducing a list of ordered objects with drag and drop:
+
+```javascript
+{
+  widget: 'object_list',
+  title: 'Items',
+  schemaName: 'mySchemaName',
+}
+```
+
+## 3.2 Creating a Custom Hero Block
+
+Let's build a hero block step by step, starting with a basic implementation and then enhancing it with VLT widgets.
+
+### Step 1: Create Basic Block Schema
+
+Create `src/components/blocks/myHero/schema.js`:
+
+```javascript
+import { defineMessages } from 'react-intl';
+
+const messages = defineMessages({
+  hero: {
+    id: 'Hero',
+    defaultMessage: 'Hero',
+  },
+  title: {
+    id: 'Title',
+    defaultMessage: 'Title',
+  },
+  subtitle: {
+    id: 'Subtitle',
+    defaultMessage: 'Subtitle',
+  },
+  backgroundImage: {
+    id: 'Background Image',
+    defaultMessage: 'Background Image',
+  },
+});
+
+const heroBlockSchema = (props) => {
+  const { intl } = props;
+
+  return {
+    title: intl.formatMessage(messages.hero),
+    fieldsets: [
+      {
+        id: 'default',
+        title: 'Default',
+        fields: ['title', 'subtitle'],
+      },
+      {
+        id: 'design',
+        title: 'Design',
+        fields: ['backgroundImage'],
+      },
+    ],
+    properties: {
+      title: {
+        title: intl.formatMessage(messages.title),
+        type: 'string',
+      },
+      subtitle: {
+        title: intl.formatMessage(messages.subtitle),
+        type: 'string',
+      },
+      backgroundImage: {
+        title: intl.formatMessage(messages.backgroundImage),
+        widget: 'object_browser',
+        mode: 'image',
+        allowExternals: false,
+      },
+    },
+    required: [],
+  };
+};
+
+export { heroBlockSchema };
+```
+
+### Step 2: Create View Component
+
+Create `src/components/blocks/myHero/View.jsx`:
+
+```jsx
+import React from 'react';
+import { withBlockExtensions } from '@plone/volto/helpers';
+import cx from 'classnames';
+import config from '@plone/volto/registry';
+import { flattenToAppURL, isInternalURL } from '@plone/volto/helpers/Url/Url';
+
+const HeroView = (props) => {
+  const { data, className, style } = props;
+  const { title, subtitle, backgroundImage } = data;
+
+  let renderedImage = null;
+  if (data.backgroundImage) {
+    let Image = config.getComponent('Image').component;
+    if (Image) {
+      renderedImage = (
+        <Image
+          item={
+            data.backgroundImage
+              ? {
+                  '@id': data.backgroundImage[0]['@id'],
+                  image_field: data.backgroundImage[0].image_field,
+                  image_scales: data.backgroundImage[0].image_scales,
+                }
+              : null
+          }
+          src={!data.image_scales ? data.url : null}
+          alt=""
+          loading="lazy"
+          responsive={true}
+        />
+      );
+    } else {
+      renderedImage = (
+        <img
+          src={
+            isInternalURL(data.url['@id'])
+              ? `${flattenToAppURL(data.url['@id'])}/@@images/image`
+              : data.url['@id']
+          }
+          alt=""
+          loading="lazy"
+        />
+      );
+    }
+  }
+
+  return (
+    <div style={style} className={cx('block hero', className)}>
+      <div className="hero-content">
+        <div className="hero-text">
+          {title && <h1 className="hero-title">{title}</h1>}
+          {subtitle && <p className="hero-subtitle">{subtitle}</p>}
+        </div>
+
+        {backgroundImage && (
+          <div className="hero-image-wrapper">{renderedImage}</div>
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default withBlockExtensions(HeroView);
+```
+
+### Step 3: Create Edit Component
+
+Create `src/components/blocks/myHero/Edit.tsx`:
+
+```tsx
+import React from 'react';
+import { useIntl } from 'react-intl';
+import SidebarPortal from '@plone/volto/components/manage/Sidebar/SidebarPortal';
+import { BlockDataForm } from '@plone/volto/components/manage/Form';
+import { heroBlockSchema } from './schema';
+import HeroView from './View';
+import type { BlockEditProps } from '@plone/types';
+
+const HeroEdit = (props: BlockEditProps) => {
+  const { selected, onChangeBlock, block, data } = props;
+  const intl = useIntl();
+
+  return (
+    <>
+      <HeroView {...props} />
+      <SidebarPortal selected={selected}>
+        <BlockDataForm
+          {...props}
+          data={data}
+          block={block}
+          schema={heroBlockSchema({ props, intl })}
+          onChangeBlock={onChangeBlock}
+          formData={data}
+          onChangeField={(id: string, value: any) => {
+            onChangeBlock(block, {
+              ...data,
+              [id]: value,
+            });
+          }}
+        />
+      </SidebarPortal>
+    </>
+  );
+};
+
+export default HeroEdit;
+```
+
+### Step 4: Register the Basic Block
+
+Update `src/config/blocks.ts`:
+
+```typescript
+import type { ConfigType } from '@plone/registry';
+import HeroView from '../components/blocks/myHero/View';
+import HeroEdit from '../components/blocks/myHero/Edit';
+import { heroBlockSchema } from '../components/blocks/myHero/schema.js';
+import heroSVG from '@plone/volto/icons/hero.svg';
+
+export default function install(config: ConfigType) {
+  // ... block themes configuration ...
+
+  // Register Hero Block
+  config.blocks.blocksConfig.hero = {
+    id: 'hero',
+    title: 'Hero',
+    icon: heroSVG,
+    group: 'common',
+    view: HeroView,
+    edit: HeroEdit,
+    restricted: false,
+    mostUsed: true,
+    blockSchema: heroBlockSchema,
+    sidebarTab: 1,
+    category: 'hero',
+  };
+
+  return config;
+}
+```
+
+### Step 5: Add Basic Block Styles
+
+Create `src/theme/blocks/_hero.scss`:
+
+```scss
+.block.hero {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background-size: cover;
+  background-position: center;
+
+  .hero-content {
+    .hero-image-wrapper {
+      img {
+        aspect-ratio: var(--image-aspect-ratio, 16/9);
+        opacity: 0.8;
+      }
+    }
+
+    .hero-text {
+      position: absolute;
+      display: flex;
+      flex-direction: column;
+      width: 100%;
+      height: 100%;
+      padding: 4rem;
+      z-index: 2;
+
+      .hero-title {
+        font-size: 5rem;
+        font-weight: var(--font-bold);
+        margin-bottom: var(--space-3);
+        line-height: 1;
+      }
+
+      .hero-subtitle {
+        font-size: 3rem;
+        margin-bottom: var(--space-6);
+        opacity: 0.95;
+        line-height: 1;
+      }
+    }
+  }
+}
+```
+
+Import in `src/theme/_main.scss`:
+
+```scss
+@import './blocks/hero';
+@import './site';
+```
+
+### Step 6: Enhance with VLT Widgets
+
+Now let's add VLT's powerful widgets to control block width and alignment. Update the schema file to add the schema enhancer.
+
+Update `src/components/blocks/myHero/schema.js`:
+
+```javascript
+import { defineMessages } from 'react-intl';
+
+const messages = defineMessages({
+  hero: {
+    id: 'Hero',
+    defaultMessage: 'Hero',
+  },
+  title: {
+    id: 'Title',
+    defaultMessage: 'Title',
+  },
+  subtitle: {
+    id: 'Subtitle',
+    defaultMessage: 'Subtitle',
+  },
+  backgroundImage: {
+    id: 'Background Image',
+    defaultMessage: 'Background Image',
+  },
+  blockWidth: {
+    id: 'Block Width',
+    defaultMessage: 'Block Width',
+  },
+  textAlignment: {
+    id: 'Text Alignment',
+    defaultMessage: 'Text Alignment',
+  },
+});
+
+const heroBlockSchema = (props) => {
+  const { intl } = props;
+
+  return {
+    title: intl.formatMessage(messages.hero),
+    fieldsets: [
+      {
+        id: 'default',
+        title: 'Default',
+        fields: ['title', 'subtitle'],
+      },
+      {
+        id: 'design',
+        title: 'Design',
+        fields: ['backgroundImage'],
+      },
+    ],
+    properties: {
+      title: {
+        title: intl.formatMessage(messages.title),
+        type: 'string',
+      },
+      subtitle: {
+        title: intl.formatMessage(messages.subtitle),
+        type: 'string',
+      },
+      backgroundImage: {
+        title: intl.formatMessage(messages.backgroundImage),
+        widget: 'object_browser',
+        mode: 'image',
+        allowExternals: false,
+      },
+    },
+    required: [],
+  };
+};
+
+// Schema enhancer to add VLT widget styling fields
+const heroSchemaEnhancer = ({ formData, schema, intl }) => {
+  // Add custom fields to the styling schema at the beginning
+  schema.properties.styles.schema.fieldsets[0].fields = [
+    'blockWidth:noprefix',
+    'align',
+    ...schema.properties.styles.schema.fieldsets[0].fields,
+  ];
+
+  schema.properties.styles.schema.properties['blockWidth:noprefix'] = {
+    widget: 'blockWidth',
+    title: intl.formatMessage(messages.blockWidth),
+    default: 'default',
+  };
+
+  schema.properties.styles.schema.properties.align = {
+    widget: 'blockAlignment',
+    title: intl.formatMessage(messages.textAlignment),
+    default: 'center',
+  };
+
+  return schema;
+};
+
+export { heroBlockSchema, heroSchemaEnhancer };
+```
+
+### Step 7: Update Block Registration with Schema Enhancer
+
+Update `src/config/blocks.ts` to include the schema enhancer:
+
+```typescript
+import type { ConfigType } from '@plone/registry';
+import HeroView from '../components/blocks/myHero/View';
+import HeroEdit from '../components/blocks/myHero/Edit';
+import {
+  heroBlockSchema,
+  heroSchemaEnhancer,
+} from '../components/blocks/myHero/schema.js';
+import { composeSchema } from '@plone/volto/helpers/Extensions';
+import { defaultStylingSchema } from '@kitconcept/volto-light-theme/components/Blocks/schema';
+import heroSVG from '@plone/volto/icons/hero.svg';
+
+export default function install(config: ConfigType) {
+  // ... block themes configuration ...
+
+  // Register Hero Block
+  config.blocks.blocksConfig.hero = {
+    id: 'hero',
+    title: 'Hero',
+    icon: heroSVG,
+    group: 'common',
+    view: HeroView,
+    edit: HeroEdit,
+    restricted: false,
+    mostUsed: true,
+    blockSchema: heroBlockSchema,
+    schemaEnhancer: composeSchema(defaultStylingSchema, heroSchemaEnhancer),
+    sidebarTab: 1,
+    category: 'hero',
+  };
+
+  return config;
+}
+```
+
+### Step 8: Update Styles to Use Widget Values
+
+Update `src/theme/blocks/_hero.scss` to use the CSS custom properties set by the widgets:
+
+```scss
+.block.hero {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background-size: cover;
+  background-position: center;
+  background-color: var(--theme-color);
+  color: var(--theme-foreground-color);
+  max-width: var(--block-width) !important;
+  margin-left: auto;
+  margin-right: auto;
+
+  .hero-content {
+    .hero-image-wrapper {
+      img {
+        aspect-ratio: var(--image-aspect-ratio, 16/9);
+        opacity: 0.8;
+      }
+    }
+
+    .hero-text {
+      position: absolute;
+      display: flex;
+      flex-direction: column;
+      align-items: var(--align--block-alignment);
+      width: 100%;
+      height: 100%;
+      padding: 4rem;
+      z-index: 2;
+
+      .hero-title {
+        font-size: 5rem;
+        font-weight: var(--font-bold);
+        margin-bottom: var(--space-3);
+        line-height: 1;
+      }
+
+      .hero-subtitle {
+        font-size: 3rem;
+        margin-bottom: var(--space-6);
+        opacity: 0.95;
+        line-height: 1;
+      }
+    }
+  }
+}
+```
+
+## 3.3 Integrating Third-Party Blocks
+
+Let's learn how to integrate the `@plone-collective/volto-relateditems-block` into VLT.
+
+### Install the Block
+
+```bash
+pnpm install @plone-collective/volto-relateditems-block@latest
+```
+
+Add it to your `package.json` addons (before VLT):
+
+```json
+"addons": [
+  "@eeacms/volto-accordion-block",
+  "@kitconcept/volto-button-block",
+  "@kitconcept/volto-heading-block",
+  "@kitconcept/volto-highlight-block",
+  "@kitconcept/volto-introduction-block",
+  "@kitconcept/volto-separator-block",
+  "@kitconcept/volto-slider-block",
+  "@plone-collective/volto-relateditems-block",
+  "@kitconcept/volto-light-theme"
+],
+```
+
+### Enhance the Block Schema
+
+To add the Block Width widget to the Related Items block, create a schema enhancer file.
+
+Create `src/components/blocks/relatedItems/schemaEnhancer.js`:
+
+```javascript
+import { defineMessages } from 'react-intl';
+
+const messages = defineMessages({
+  blockWidth: {
+    id: 'Block Width',
+    defaultMessage: 'Block Width',
+  },
+});
+
+const relatedItemsSchemaEnhancer = ({ formData, schema, intl }) => {
+  schema.properties.styles.schema.fieldsets[0].fields = [
+    'blockWidth:noprefix',
+    ...schema.properties.styles.schema.fieldsets[0].fields,
+  ];
+
+  schema.properties.styles.schema.properties['blockWidth:noprefix'] = {
+    widget: 'blockWidth',
+    title: intl.formatMessage(messages.blockWidth),
+    default: 'default',
+    filterActions: ['narrow', 'default'],
+  };
+
+  return schema;
+};
+
+export default relatedItemsSchemaEnhancer;
+```
+
+Then update `src/config/blocks.ts` to register the enhancer:
+
+```typescript
+import { composeSchema } from '@plone/volto/helpers/Extensions';
+import { defaultStylingSchema } from '@kitconcept/volto-light-theme/components/Blocks/schema';
+import relatedItemsSchemaEnhancer from '../components/blocks/relatedItems/schemaEnhancer';
+
+export default function install(config: ConfigType) {
+  // ... previous configuration ...
+
+  config.blocks.blocksConfig.relatedItems = {
+    ...config.blocks.blocksConfig.relatedItems,
+    schemaEnhancer: composeSchema(defaultStylingSchema, relatedItemsSchemaEnhancer),
+  };
+
+  return config;
+}
+```
+
+### Add Custom Styles
+
+Create `src/theme/blocks/_relatedItems.scss`:
+
+```scss
+.block.relatedItems {
+  max-width: var(--block-width);
+  margin-right: auto;
+  margin-left: auto;
+
+  .inner-container {
+    background: var(--theme-high-contrast-color);
+    padding: 3rem;
+
+    h2.headline {
+      color: var(--theme-foreground-color);
+    }
+
+    ul {
+      color: var(--theme-foreground-color);
+      li a {
+        color: var(--link-foreground-color);
+      }
+    }
+  }
+
+
+}
+
+```
+
+Import it in `_main.scss`:
+
+```scss
+@import './blocks/hero';
+@import './blocks/relatedItems';
+@import './site';
+```
+
+---
diff --git a/docs/customizing-volto-light-theme/concepts.md b/docs/customizing-volto-light-theme/concepts.md
index 91eba4414..70ef7e4cd 100644
--- a/docs/customizing-volto-light-theme/concepts.md
+++ b/docs/customizing-volto-light-theme/concepts.md
@@ -1,35 +1,38 @@
 ---
 myst:
   html_meta:
-    "description": "Concepts"
-    "property=og:description": "Concepts"
-    "property=og:title": "Concepts"
+    "description": "Foundation, Concepts & Project Setup"
+    "property=og:description": "Foundation, Concepts & Project Setup"
+    "property=og:title": "Foundation, Concepts & Project Setup"
     "keywords": "Plone, Volto, Training, Volto Light Theme"
 ---
+# 1. Foundation, Concepts & Project Setup
 
-# Volto Light Theme Concepts
+## 1.1 Volto Light Theme Core Concepts
 
 Volto Light Theme (VLT) is a customizable theme built for the Volto frontend of the Plone CMS. It provides a foundation that aims to solve many common design challenges, while remaining flexible enough for customization. It's particularly valuable because it is based on real-world experience, while simultaneously embodying the Volto vision for the future. This module will help you understand the core concepts in VLT and create a mental map of its parts.
 
-## Base Styling
+### Base Styling
 
-VLT is designed with simplicity and a minimal aesthetic in mind. Consistency, accessibility, and intuitiveness are what drive the development and improvements for VLT.
+VLT is designed with simplicity and a minimal aesthetic in mind. The three core principles are:
+- **Consistency**: Predictable design patterns across all components
+- **Accessibility**: WCAG compliant with contrast checkers and semantic HTML
+- **Intuitiveness**: Clear visual hierarchy and user-friendly interfaces
 
-## Customizable Variables
+### Customizable Variables
 
-VLT offers a set of CSS custom properties (variables) that allow developers to customize various design elements, such as:
-
-- Colors
-- Spatial relationships
-- Layouts
+VLT offers a set of CSS custom properties (variables) that allow developers to customize various design elements:
+- **Colors**: Using paired foreground/background color system
+- **Spatial relationships**: Container widths and spacing scales
+- **Layouts**: Three-width container system
 
 These variables can be easily overridden in your project to match the desired visual identity.
 
-## Colors
+### Color System
 
-The color system is designed so that colors work in couples: a "background color" and a "foreground color". The "foreground color" is often called "text color" in other systems, but since we want to use this value for more than text—like icons or borders, this works better as a generic term. Colors that do not specify "foreground" in the name are meant to be background colors.
+The color system is designed so that colors work in couples: a "background color" and a "foreground color". The "foreground color" is often called "text color" in other systems, but since we want to use this value for more than text—like icons or borders—this works better as a generic term. Colors that do not specify "foreground" in the name are meant to be background colors.
 
-The main color properties for a project using VLT are the following:
+The main color properties for a project using VLT are:
 
 ```scss
 --primary-color: #fff;
@@ -42,9 +45,9 @@ The main color properties for a project using VLT are the following:
 --accent-foreground-color: #000;
 ```
 
-### Semantic color properties
+### Semantic Color Properties
 
-As an additional layer on top of the main color properties, we have set in place some semantic custom properties for the basic layout sections. As a default they use the values from the main color variables, but they can be detached if desired by setting new color values. However, we feel that leaving these color relationships as they are helps create a cohesive final design. The semantic layer of properties includes the following:
+As an additional layer on top of the main color properties, we have set in place some semantic custom properties for the basic layout sections. As a default they use the values from the main color variables, but they can be detached if desired by setting new color values. However, leaving these color relationships as they are helps create a cohesive final design:
 
 ```scss
 // Header
@@ -71,32 +74,64 @@ As an additional layer on top of the main color properties, we have set in place
 --link-foreground-color: var(--link-color);
 ```
 
-## Block width
+### Block Themes
+
+VLT includes a block theme system that enables individual blocks to use distinct color palettes. These themes are configured in `config.blocks.themes` and applied through the StyleWrapper system at runtime.
+
+**The four core block theme variables:**
+
+- `--theme-color`: Primary background color — the most visible color in the block
+- `--theme-high-contrast-color`: Secondary background color for nested elements (e.g., cards within a block) to create visual separation from the main background
+- `--theme-foreground-color`: Default text and icon color
+- `--theme-low-contrast-foreground-color`: Subdued text color for secondary content like placeholders or helper text
+
+While the system can be extended with non-color CSS properties, the default four variables establish the color foundation for each theme.
+
+**Example configuration:**
+
+```typescript
+config.blocks.themes = [
+  {
+    style: {
+      '--theme-color': '#fff',
+      '--theme-high-contrast-color': '#ecebeb',
+      '--theme-foreground-color': '#000',
+      '--theme-low-contrast-foreground-color': '#555555',
+    },
+    name: 'default',
+    label: 'Default',
+  },
+  {
+    style: {
+      '--theme-color': '#ecebeb',
+      '--theme-high-contrast-color': '#fff',
+      '--theme-foreground-color': '#000',
+      '--theme-low-contrast-foreground-color': '#555555',
+    },
+    name: 'grey',
+    label: 'Grey',
+  },
+];
+```
 
-VLT now uses a standard block width definition as well. Currently, this is done via a `widget` component, `BlockWidthWidget`, that will be ported to Volto core in the near future. This component stores the value of the custom property `--block-width` so that it can be used by the StyleWrapper when injecting styles into the markup.
+Users select block themes through the `themeColorSwatch` widget in the block sidebar. This widget renders colored buttons using each theme's `--theme-color` value, allowing visual theme selection.
 
-The three-width layout system considers the following variables:
+### Container Width System
 
-```scss
---layout-container-width: #{$layout-container-width}; // for major elements like headers, & large Blocks like the `volto-slider-block`. 
---default-container-width: #{$default-container-width}; // a balanced content presentation for most Blocks.
---narrow-container-width: #{$narrow-container-width}; // optimal readability.
-```
-
-The default values map the container width SCSS variables, which have existed in the VLT ecosystem since versions < 6.0.0-alpha.0:
+VLT uses three types of container widths:
 
 ```scss
-// Container widths
-$layout-container-width: 1440px !default;
-$default-container-width: 940px !default;
-$narrow-container-width: 620px !default;
+// Three-width layout system
+--layout-container-width: 1440px;  // for major elements like headers & large Blocks
+--default-container-width: 940px;  // balanced content presentation for most Blocks
+--narrow-container-width: 620px;   // optimal readability for text
 ```
 
-## Block alignment
+The VLT `BlockWidthWidget` stores the value of the custom property `--block-width` so that it can be used by the StyleWrapper when injecting styles into the markup.
 
-As part of the effort to generalize behaviors, another VLT `widget` is the `BlockAlignmentWidget`, which also takes advantage of the StyleWrapper by setting the `--block-alignment` property.
+### Block Alignment
 
-The three default options are:
+The `BlockAlignmentWidget` takes advantage of the StyleWrapper by setting the `--block-alignment` property. The three default options are:
 
 ```scss
 --align-left: start;
@@ -104,6 +139,148 @@ The three default options are:
 --align-right: end;
 ```
 
-## Conclusion
+## 1.2 Create a New Project with Cookieplone
+
+We recommend creating your Plone project with **Cookieplone**. Our comprehensive documentation provides step-by-step guidance to help you get started. For detailed installation instructions, visit our [Cookieplone guide](https://6.docs.plone.org/install/create-project-cookieplone.html).
+
+## 1.3 Installing Volto Light Theme
+
+### Step 1: Install VLT and Recommended Block Add-ons
+
+Navigate to the `frontend/packages/my-vlt-project` folder and install VLT:
+
+```bash
+pnpm install @kitconcept/volto-light-theme@latest
+```
+
+Volto Light Theme comes with several pre-configured add-ons that provide basic blocks for your website. If you'd like to include them, you can add them in the `addons` section in your {file}`package.json`, but this is not required.
+
+Here is the list of recommended addons to install, including VLT, which should be the last element:
+
+```json
+"addons": [
+  "@eeacms/volto-accordion-block",
+  "@kitconcept/volto-button-block",
+  "@kitconcept/volto-heading-block",
+  "@kitconcept/volto-highlight-block",
+  "@kitconcept/volto-introduction-block",
+  "@kitconcept/volto-separator-block",
+  "@kitconcept/volto-slider-block",
+  "@kitconcept/volto-light-theme"
+],
+```
+
+While in your project package folder, add VLT and the block addons to the `addons` list in your `package.json`:
+
+```json
+{
+  "name": "my-vlt-project",
+  "addons": [
+    "@eeacms/volto-accordion-block",
+    "@kitconcept/volto-button-block",
+    "@kitconcept/volto-heading-block",
+    "@kitconcept/volto-highlight-block",
+    "@kitconcept/volto-introduction-block",
+    "@kitconcept/volto-separator-block",
+    "@kitconcept/volto-slider-block",
+    "@kitconcept/volto-light-theme"
+  ]
+}
+```
+
+**Important:** VLT must be the last addon in the list to ensure proper style cascade. Your project addon will still be the last applied if defined in `volto.config.js`.
+
+### Step 2: Configure VLT as the Theme Provider
+
+Open the `volto.config.js` file in your `frontend` folder and modify it as shown below:
+
+```javascript
+const addons = ['my-vlt-project'];
+const theme = '@kitconcept/volto-light-theme';
+
+module.exports = {
+  addons,
+  theme,
+};
+```
+
+You'll need to restart your Plone frontend to see the changes.
+
+That's it! Your project should now be using Volto Light Theme with its additional blocks and components.
+
+### Step 3: Install Backend Package
+
+In your backend folder, install the Python package for site customization behaviors.
+
+Edit `backend/pyproject.toml` and add to the dependencies array:
+
+```
+dependencies = [
+    "Products.CMFPlone==6.1.3",
+    "plone.api",
+    "plone.restapi",
+    "plone.volto",
+    "kitconcept.voltolighttheme==7.3.0",
+]
+```
+
+### Step 4: Install the Backend Add-on
+
+Start your development environment:
+
+```bash
+# Terminal 1 - Backend
+make backend-start
+
+# Terminal 2 - Frontend
+make frontend-start
+```
+
+Once the frontend is running:
+
+1. Go to http://localhost:3000/controlpanel/addons
+2. Find "Volto Light Theme" in the list
+3. Click "Install"
+
+### Step 5: Activate Behaviors for Plone Site
+
+To enable site customization through the UI:
+
+1. Go to http://localhost:3000/controlpanel/dexterity-types/Plone%20Site
+2. In the "Behaviors" tab, activate the desired behaviors
+3. Click "Save"
+
+Now your project should have the VLT Site configurations available.
+
+## 1.4 File Structure Setup
+
+Let's set up the recommended file structure. In your project add-on's `src` folder, create the following structure:
+
+```console
+src/
+├── components/
+│   └── blocks/
+├── config/
+│   ├── settings.ts
+│   └── blocks.ts
+├── index.ts
+└── theme/
+    ├── blocks/
+    ├── _main.scss
+    └── _site.scss
+```
+
+Create the files:
+
+```bash
+cd src
+mkdir -p components/blocks config theme/blocks
+touch config/settings.ts config/blocks.ts
+touch index.ts
+touch theme/_main.scss theme/_site.scss
+```
+
+Remember that if you add new files to your project, it will be necessary to restart your Plone frontend.
+
 
-VLT provides a robust foundation for Plone CMS frontend development through this framework of customizable variables and standardized block controls. Through these core concepts, VLT strikes a balance between maintaining consistency and flexibility, allowing developers to create cohesive designs while still having the freedom to customize elements to match their specific project needs.
+---
\ No newline at end of file
diff --git a/docs/customizing-volto-light-theme/creating-new-project.md b/docs/customizing-volto-light-theme/creating-new-project.md
deleted file mode 100644
index 9cc7fef69..000000000
--- a/docs/customizing-volto-light-theme/creating-new-project.md
+++ /dev/null
@@ -1,11 +0,0 @@
----
-myst:
-  html_meta:
-    "description": "Create a new project with Plone and Volto"
-    "property=og:description": "Create a new project with Plone and Volto"
-    "property=og:title": "Create a new project with Plone and Volto"
-    "keywords": "Plone, Volto, Training, Theme, Footer"
----
-
-# Create a new project with Plone and Volto
-We recommend creating your Plone project with **Cookieplone**. Our comprehensive documentation provides step-by-step guidance to help you get started. For detailed installation instructions, visit our [Cookieplone guide](https://6.docs.plone.org/install/create-project-cookieplone.html).
\ No newline at end of file
diff --git a/docs/customizing-volto-light-theme/design-system-implementation.md b/docs/customizing-volto-light-theme/design-system-implementation.md
new file mode 100644
index 000000000..71cabcf3e
--- /dev/null
+++ b/docs/customizing-volto-light-theme/design-system-implementation.md
@@ -0,0 +1,453 @@
+---
+myst:
+  html_meta:
+    "description": "Design system implementation & theming"
+    "property=og:description": "Design system implementation & theming"
+    "property=og:title": "Design system implementation & theming"
+    "keywords": "Plone, Volto, Training, Theme, Footer"
+---
+
+# 2. Design System Implementation & Theming
+
+## 2.1 Extracting Design Tokens
+
+When working with a given design, systematically extract design decisions. Identify:
+
+### Color Extraction Checklist
+
+1. **Primary Colors**
+   - Background color
+   - Text color on primary
+
+2. **Secondary Colors**
+   - Background color
+   - Text color on secondary
+
+3. **Accent Colors**
+   - Highlight color
+   - Text color on accent
+
+4. **Semantic Colors**
+   - Link colors
+
+### Typography Extraction
+
+Look for:
+- Font families
+- Line heights
+- Font weights
+
+
+## 2.2 Implementing Your Design System
+
+VLT has migrated to use standardized color definitions. These use CSS properties that are injected at runtime in the right places, so your CSS can adapt to use them generically. The resulting CSS is simpler, and there's no need to define class names for each color definition.
+
+### Step 1: Create _site.scss
+
+In `src/theme/_site.scss`, define your color variables and custom properties:
+
+```scss
+@font-face {
+  font-family: 'Chakra Petch';
+  src: url('./fonts/Chakra_Petch/ChakraPetch-Regular.ttf') format('truetype');
+}
+
+:root {
+  // Extract these from your design
+  --accent-color: #3b5759;
+  --accent-foreground-color: #fff;
+  --secondary-color: #afcac8;
+
+  // Typography
+  --text-base: 1.15rem;
+  --custom-main-font: 'Chakra Petch', sans-serif;
+  --line-height-factor: 1.5;
+
+  // Gradients for header/footer
+  --header-background: linear-gradient(
+    -3deg,
+    var(--background, #fff) 0%,
+    color-mix(in oklab, var(--secondary-color) 1%, var(--background, #fff)) 20%,
+    color-mix(in oklab, var(--secondary-color) 3%, var(--background, #fff)) 35%,
+    color-mix(in oklab, var(--secondary-color) 10%, var(--background, #fff)) 50%,
+    color-mix(in oklab, var(--secondary-color) 30%, var(--background, #fff)) 65%,
+    color-mix(in oklab, var(--secondary-color) 65%, var(--background, #fff)) 80%,
+    color-mix(in oklab, var(--secondary-color) 90%, var(--background, #fff)) 92%,
+    var(--secondary-color) 100%
+  );
+
+  --footer-background: radial-gradient(
+    ellipse 100% 100% at 50% 100%,
+    var(--secondary-color) 0%,
+    var(--secondary-color) 20%,
+    color-mix(in oklab, var(--secondary-color) 85%, var(--background, #fff)) 30%,
+    color-mix(in oklab, var(--secondary-color) 65%, var(--background, #fff)) 40%,
+    color-mix(in oklab, var(--secondary-color) 45%, var(--background, #fff)) 50%,
+    color-mix(in oklab, var(--secondary-color) 30%, var(--background, #fff)) 60%,
+    color-mix(in oklab, var(--secondary-color) 18%, var(--background, #fff)) 70%,
+    color-mix(in oklab, var(--secondary-color) 10%, var(--background, #fff)) 80%,
+    color-mix(in oklab, var(--secondary-color) 4%, var(--background, #fff)) 90%,
+    var(--background, #fff) 100%
+  );
+
+  --fatmenu-foreground: #fff;
+
+  // Container widths (customized)
+  --default-container-width: 1440px;
+  --layout-container-width: 90%;
+
+  // Link color
+  --link-foreground-color: #157a7a;
+
+  // Breadcrumbs
+  --breadcrumbs-background: var(--background, #fff);
+  --breadcrumbs-foreground: var(--secondary-foreground-color, #3b5759);
+
+  .breadcrumbs {
+    border-bottom: 1px solid #afcac8;
+  }
+
+  // Block-specific styles
+  #page-document,
+  #page-edit,
+  #page-add {
+    .blocks-group-wrapper:first-child {
+      padding-top: 0;
+
+    }
+    .block {
+
+      &.__button {
+        .button {
+          button {
+            padding: 1rem;
+          }
+        }
+      }
+
+      &.__button {
+        .ui.button:hover {
+          --theme-color: #fff;
+        }
+      }
+
+      &.slider {
+        .teaser-item-title {
+          background: rgba(255, 255, 255, 0.1);
+          color: var(--theme-foreground-color) !important;
+          backdrop-filter: blur(20px) saturate(110%);
+          -webkit-backdrop-filter: blur(20px) saturate(180%);
+          box-shadow:
+            0 8px 32px 0 rgba(31, 135, 125, 0.1),
+            inset 0 0 0 1px rgba(255, 255, 255, 0.1);
+        }
+      }
+
+      &.gridBlock {
+        .four {
+          .slate:not(.inner) {
+            padding: 2.5rem;
+            padding-top: 4rem !important;
+            backdrop-filter: blur(20px) saturate(110%);
+            -webkit-backdrop-filter: blur(20px) saturate(180%);
+            box-shadow:
+              0 8px 32px 0 rgba(31, 135, 125, 0.1),
+              inset 0 0 0 1px rgba(255, 255, 255, 0.1);
+          }
+        }
+      }
+
+      &.teaser {
+        .card {
+          .card-inner {
+            .card-summary {
+              padding: $spacing-large;
+            }
+          }
+        }
+      }
+    }
+
+
+  }
+}
+
+#sidebar {
+ .color-swatch-widget {
+      .buttons button.teal {
+        background: linear-gradient(135deg, var(--secondary-color) 0%, #fff 100%);
+      }
+    }
+}
+```
+
+### Step 2: Configure Block Themes
+
+In `src/config/blocks.ts`, define block themes:
+
+```typescript
+import type { ConfigType } from '@plone/registry';
+
+export default function install(config: ConfigType) {
+  // Block palettes
+    config.blocks.themes = [
+    {
+      style: {
+        '--theme-color': 'white',
+        '--theme-high-contrast-color': '#bbd1d0',
+        '--theme-foreground-color': 'black',
+        '--theme-low-contrast-foreground-color': '#555555',
+      },
+      name: 'default',
+      label: 'Default',
+    },
+    {
+      style: {
+        '--theme-color': `/* White edge bleed for continuity */
+                linear-gradient(180deg,
+                    rgba(255, 255, 255, 0.9) 0%,
+                    rgba(255, 255, 255, 0.6) 8%,
+                    rgba(255, 255, 255, 0.3) 12%,
+                    transparent 18%,
+                    transparent 82%,
+                    rgba(255, 255, 255, 0.3) 88%,
+                    rgba(255, 255, 255, 0.6) 92%,
+                    rgba(255, 255, 255, 0.9) 100%),
+
+                /* Top white highlights - asymmetric cluster */
+                radial-gradient(ellipse 900px 650px at 12% 8%,
+                    rgba(255, 255, 255, 0.38) 0%,
+                    rgba(243, 251, 251, 0.26) 28%,
+                    rgba(228, 244, 244, 0.14) 52%,
+                    transparent 72%),
+
+                radial-gradient(ellipse 750px 850px at 6% 22%,
+                    rgba(255, 255, 255, 0.34) 0%,
+                    rgba(238, 249, 249, 0.2) 32%,
+                    rgba(220, 240, 240, 0.1) 58%,
+                    transparent 78%),
+
+                radial-gradient(ellipse 820px 580px at 88% 12%,
+                    rgba(255, 255, 255, 0.42) 0%,
+                    rgba(246, 252, 252, 0.28) 30%,
+                    rgba(232, 246, 246, 0.15) 54%,
+                    transparent 74%),
+
+                /* Bottom white highlights - dispersed asymmetrically */
+                radial-gradient(ellipse 980px 620px at 82% 88%,
+                    rgba(255, 255, 255, 0.4) 0%,
+                    rgba(244, 251, 251, 0.27) 26%,
+                    rgba(230, 245, 245, 0.13) 50%,
+                    transparent 73%),
+
+                radial-gradient(ellipse 680px 780px at 18% 90%,
+                    rgba(255, 255, 255, 0.35) 0%,
+                    rgba(240, 250, 250, 0.22) 34%,
+                    rgba(225, 242, 242, 0.11) 60%,
+                    transparent 80%),
+
+                radial-gradient(ellipse 720px 520px at 68% 94%,
+                    rgba(255, 255, 255, 0.3) 0%,
+                    rgba(235, 247, 247, 0.17) 38%,
+                    transparent 68%),
+
+                /* Color hotspot 1 - upper right quadrant */
+                radial-gradient(ellipse 850px 750px at 70% 35%,
+                    rgba(175, 202, 200, 0.5) 0%,
+                    rgba(180, 206, 204, 0.38) 25%,
+                    rgba(190, 212, 210, 0.24) 45%,
+                    rgba(200, 220, 218, 0.12) 65%,
+                    transparent 85%),
+
+                /* Color hotspot 2 - lower left quadrant */
+                radial-gradient(ellipse 920px 800px at 25% 65%,
+                    rgba(165, 195, 193, 0.45) 0%,
+                    rgba(175, 202, 200, 0.34) 28%,
+                    rgba(185, 210, 208, 0.22) 50%,
+                    rgba(195, 215, 213, 0.11) 70%,
+                    transparent 87%),
+
+                /* Color hotspot 3 - center right */
+                radial-gradient(circle 700px at 78% 52%,
+                    rgba(170, 198, 196, 0.42) 0%,
+                    rgba(180, 205, 203, 0.3) 30%,
+                    rgba(192, 214, 212, 0.18) 55%,
+                    rgba(205, 222, 220, 0.09) 75%,
+                    transparent 90%),
+
+                /* Organic flow connecting hotspots */
+                radial-gradient(ellipse 1100px 900px at 45% 48%,
+                    rgba(175, 202, 200, 0.28) 0%,
+                    rgba(185, 210, 208, 0.18) 35%,
+                    rgba(195, 216, 214, 0.1) 60%,
+                    rgba(205, 222, 220, 0.05) 78%,
+                    transparent 90%),
+
+                /* Additional scattered color pockets */
+                radial-gradient(circle 550px at 15% 40%,
+                    rgba(172, 198, 196, 0.32) 0%,
+                    rgba(182, 207, 205, 0.2) 38%,
+                    rgba(195, 216, 214, 0.1) 68%,
+                    transparent 85%),
+
+                radial-gradient(ellipse 680px 580px at 88% 68%,
+                    rgba(178, 203, 201, 0.35) 0%,
+                    rgba(188, 210, 208, 0.22) 35%,
+                    rgba(200, 218, 216, 0.11) 65%,
+                    transparent 82%),
+
+                radial-gradient(ellipse 620px 720px at 52% 28%,
+                    rgba(168, 196, 194, 0.3) 0%,
+                    rgba(180, 205, 203, 0.18) 40%,
+                    rgba(195, 215, 213, 0.08) 70%,
+                    transparent 88%),
+
+                radial-gradient(circle 480px at 35% 78%,
+                    rgba(175, 200, 198, 0.28) 0%,
+                    rgba(188, 210, 208, 0.15) 42%,
+                    transparent 75%),
+
+                /* Asymmetrical accent flows */
+                conic-gradient(from 125deg at 28% 44%,
+                    transparent 0deg,
+                    rgba(178, 203, 201, 0.18) 48deg,
+                    rgba(185, 210, 208, 0.14) 95deg,
+                    transparent 145deg,
+                    rgba(172, 198, 196, 0.12) 235deg,
+                    transparent 285deg),
+
+                /* Base gradient foundation - subtle */
+                linear-gradient(182deg,
+                    #ffffff 0%,
+                    #f9fcfc 10%,
+                    #ebf4f3 22%,
+                    #d8e6e5 35%,
+                    #c5d8d6 45%,
+                    #b8cece 52%,
+                    #c5d8d6 59%,
+                    #d8e6e5 69%,
+                    #ebf4f3 82%,
+                    #f9fcfc 92%,
+                    #ffffff 100%)`,
+        '--theme-high-contrast-color': 'rgba(255, 255, 255, 0.1)',
+        '--theme-foreground-color': 'black',
+        '--theme-low-contrast-foreground-color': '#555555',
+      },
+      name: 'teal',
+      label: 'Teal',
+    },
+  ];
+
+  return config;
+}
+```
+
+### Step 3: Configure Settings
+
+In `src/config/settings.ts`:
+
+```typescript
+import type { ConfigType } from '@plone/registry';
+import installBlocks from './blocks';
+
+export default function install(config: ConfigType) {
+  // Language settings
+  config.settings.isMultilingual = false;
+  config.settings.supportedLanguages = ['en'];
+  config.settings.defaultLanguage = 'en';
+
+  installBlocks(config);
+
+  return config;
+}
+```
+
+### Step 4: Main Index Configuration
+
+In `src/index.ts`:
+
+```typescript
+import type { ConfigType } from '@plone/registry';
+import installSettings from './config/settings';
+
+function applyConfig(config: ConfigType) {
+  installSettings(config);
+  return config;
+}
+
+export default applyConfig;
+```
+
+### Step 5: Import SCSS Files
+
+In `src/theme/_main.scss`:
+
+```scss
+@import './site';
+```
+
+## 2.3 Customizing Block Styles
+
+Let's add custom styles for specific blocks. In your `_site.scss`, add block-specific styles:
+
+```scss
+:root {
+  // ... previous variables ...
+
+  #page-document {
+    .block {
+      &.__button {
+        .button {
+          button {
+            padding: 1rem;
+          }
+        }
+      }
+
+      &.__button {
+        .ui.button:hover {
+          --theme-color: white;
+        }
+      }
+
+      &.slider {
+        .teaser-item-title {
+          background: rgba(255, 255, 255, 0.1);
+          color: var(--theme-foreground-color) !important;
+          backdrop-filter: blur(20px) saturate(110%);
+          -webkit-backdrop-filter: blur(20px) saturate(180%);
+          box-shadow:
+            0 8px 32px 0 rgba(31, 135, 125, 0.1),
+            inset 0 0 0 1px rgba(255, 255, 255, 0.1);
+        }
+      }
+
+      &.gridBlock {
+        .four {
+          .slate {
+            padding: 2.5rem;
+            padding-top: 4rem !important;
+            backdrop-filter: blur(20px) saturate(110%);
+            -webkit-backdrop-filter: blur(20px) saturate(180%);
+            box-shadow:
+              0 8px 32px 0 rgba(31, 135, 125, 0.1),
+              inset 0 0 0 1px rgba(255, 255, 255, 0.1);
+          }
+        }
+      }
+
+      &.teaser {
+        .card {
+          .card-inner {
+            .card-summary {
+              padding: $spacing-large;
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+---
\ No newline at end of file
diff --git a/docs/customizing-volto-light-theme/index.md b/docs/customizing-volto-light-theme/index.md
index 74e398160..04260b9a7 100644
--- a/docs/customizing-volto-light-theme/index.md
+++ b/docs/customizing-volto-light-theme/index.md
@@ -28,9 +28,8 @@ This training is best suited for developers who have prior experience with Volto
 :numbered:
 
 concepts
-creating-new-project
-installing-vlt
-integrate-new-block
-theming
+design-system-implementation
+block-development-widgets
+advanced-components-bm3
 question-answer
 ```
\ No newline at end of file
diff --git a/docs/customizing-volto-light-theme/installing-vlt.md b/docs/customizing-volto-light-theme/installing-vlt.md
deleted file mode 100644
index 32cc59343..000000000
--- a/docs/customizing-volto-light-theme/installing-vlt.md
+++ /dev/null
@@ -1,71 +0,0 @@
----
-myst:
-  html_meta:
-    "description": "Installing Volto Light Theme"
-    "property=og:description": "Installing Volto Light Theme"
-    "property=og:title": "Installing Volto Light Theme"
-    "keywords": "Plone, Volto, Training, Volto Light Theme"
----
-
-# Installing Volto Light Theme
-
-Follow the steps below to install and configure VLT in your project. VLT provides a clean and modern design with ready-to-use blocks and components.
-
-## Step 1: Install Volto Light Theme
-
-To install VLT, navigate to the {file}`frontend/packages/volto-my-project` folder and run the following command:
-
-```{note}
-For now we'll be using an `alpha` release, so we need to specify the correct version.
-```
-
-```shell
-pnpm install @kitconcept/volto-light-theme@6.0.0-alpha.2
-```
-
-While in your project package folder, add VLT to the `addons` list in your {file}`package.json`, as follows:
-
-```json
-"addons": ["@kitconcept/volto-light-theme"],
-```
-
-## Step 2: install block add-ons
-
-Volto Light Theme comes with several pre-configured add-ons that provide basic blocks for your website. If you'd like to include them, you can add them in the `addons` section in your {file}`package.json`, but this is not required.
-
-Here is the list of recommended addons to install, including VLT, which should be the last element:
-
-```json
-"addons": [
-  "@eeacms/volto-accordion-block",
-  "@kitconcept/volto-button-block",
-  "@kitconcept/volto-heading-block",
-  "@kitconcept/volto-highlight-block",
-  "@kitconcept/volto-introduction-block",
-  "@kitconcept/volto-separator-block",
-  "@kitconcept/volto-slider-block",
-  "@kitconcept/volto-light-theme"
-],
-```
-
-## Step 3: configure Volto Light Theme as the theme provider
-
-To leverage a cohesive set of styles, components, and design patterns that align with Volto's best practices, you need to set VLT as your theme provider.
-
-Open the {file}`volto.config.js` file in your {file}`frontend` folder, and modify it as shown below.
-
-```{code-block} js
-:emphasize-lines: 2
-
-const addons = ['volto-project-title'];
-const theme = '@kitconcept/volto-light-theme';
-
-module.exports = {
-  addons,
-  theme
-};
-```
-
-You'll need to restart your Plone frontend to see the changes.
-
-That's it! Your project should now be using Volto Light Theme with its additional blocks and components.
diff --git a/docs/customizing-volto-light-theme/integrate-new-block.md b/docs/customizing-volto-light-theme/integrate-new-block.md
deleted file mode 100644
index 7086e08b4..000000000
--- a/docs/customizing-volto-light-theme/integrate-new-block.md
+++ /dev/null
@@ -1,44 +0,0 @@
----
-myst:
-  html_meta:
-    "description": "Adding New Block"
-    "property=og:description": "Adding New Block"
-    "property=og:title": "Adding New Block"
-    "keywords": "Plone, Volto, Training, Volto Light Theme, Integrate, block"
----
-
-# Integrate a new block
-
-In this training module, we'll learn how to integrate the `@plone-collective/volto-relateditems-block` into VLT. This block allows you to create links to related content in your Plone site.
-
-## Install `@plone-collective/volto-relateditems-block`
-
-To install the related items block, make sure you are in the {file}`frontend/packages/volto-my-project` folder, and use the following command:
-
-```{note}
-For now we'll be using an `alpha` release, so we need to specify the correct version.
-```
-
-```shell
-pnpm install @plone-collective/volto-relateditems-block@1.0.0-alpha.1
-```
-
-After installation, ensure that the add-on is included in the `addons` key of your project's {file}`package.json`:
-
-```json
-"addons": [
-  "@eeacms/volto-accordion-block",
-  "@kitconcept/volto-button-block",
-  "@kitconcept/volto-heading-block",
-  "@kitconcept/volto-highlight-block",
-  "@kitconcept/volto-introduction-block",
-  "@kitconcept/volto-separator-block",
-  "@kitconcept/volto-slider-block",
-  "@plone-collective/volto-relateditems-block",
-  "@kitconcept/volto-light-theme"
-],
-```
-
-You'll need to restart your Plone frontend to see the changes.
-
-That's it! Your project should now be using `@plone-collective/volto-relateditems-block`, which shows related items for the content as a list of links.
diff --git a/docs/customizing-volto-light-theme/theming.md b/docs/customizing-volto-light-theme/theming.md
deleted file mode 100644
index 5e3d94699..000000000
--- a/docs/customizing-volto-light-theme/theming.md
+++ /dev/null
@@ -1,342 +0,0 @@
----
-myst:
-  html_meta:
-    "description": "Extend the Volto Light Theme"
-    "property=og:description": "Extend the Volto Light Theme"
-    "property=og:title": "Extend the Volto Light Theme"
-    "keywords": "Plone, Volto, Training, Extend, Volto Light Theme"
----
-
-# Extend VLT
-
-In this section we'll extend the VLT to create a "dark" aesthetic for our project. The same patterns can be applied for other visual identity cases.
-
-## File structure
-
-Let us start by setting up the recommended file structure. In your project add-on's {file}`src` folder, create a subfolder named {file}`theme`.
-Inside {file}`theme` create two empty files named {file}`_main.scss` and {file}`_variables.scss`. Refer to the following file system diagram:
-
-```console
-src/
-├── components
-├── index.js
-└── theme
-    ├── _main.scss
-    └── _variables.scss
-```
-
-Remember that if you add new files to your project, it will be necessary to restart your Plone frontend.
-
-### `_variables.scss`
-
-{file}`_variables.scss` is where you can override the base theme SCSS variables.
-
-```scss
-:root {
-    --primary-color: black;
-    --primary-foreground-color: lemonchiffon;
-
-    --secondary-color: darkslategrey;
-    --secondary-foreground-color: lemonchiffon;
-
-    --accent-color: darkslategrey;
-    --accent-foreground-color: lemonchiffon;
-
-    --link-color: lightblue;
-}
-```
-
-### `_main.scss`
-
-{file}`_main.scss` is where you should put any custom styles. You can also include other SCSS or CSS files, as follows:
-
-```scss
-@import 'variables';
-```
-
-## Block themes
-
-Now we need to change the available themes for the blocks by adding the following definition inside the `applyConfig` function in our project's {file}`index.js`:
-
-```js
-config.blocks.themes = [
-  {
-    style: {
-      '--theme-color': 'black',
-      '--theme-high-contrast-color': 'darkslategrey',
-      '--theme-foreground-color': 'lemonchiffon',
-      '--theme-low-contrast-foreground-color': 'lightgrey',
-    },
-    name: 'default',
-    label: 'Default',
-  },
-  {
-    style: {
-      '--theme-color': 'darkslategrey',
-      '--theme-high-contrast-color': 'black',
-      '--theme-foreground-color': 'lemonchiffon',
-      '--theme-low-contrast-foreground-color': 'lightgrey',
-    },
-    name: 'green',
-    label: 'Green',
-  },
-];
-```
-
-## Extend add-on styles
-
-The theme provides the ability to extend or modify existing components. Let's create one more file named {file}`relatedItems.scss` to add specific styles for the add-on, as follows:
-
-```console
-src/
-├── components
-├── index.js
-└── theme
-    ├── blocks
-        └── _relatedItems.scss
-    ├── _main.scss
-    └── _variables.scss
-```
-
-In the new {file}`_relatedItems.scss`, let's fix the text color, and add background color to the `.inner-container` element with the variables `--primary-foreground-color` and `--theme-high-contrast-color`. Lastly, let's use `--link-foreground-color` for the related items links:
-
-```scss
-.block.relatedItems {
-  .inner-container {
-    background: var(--theme-high-contrast-color);
-    padding: 3rem;
-
-    h2.headline {
-        color: var(--primary-foreground-color);
-    }
-
-    ul.items-list {
-      color: var(--primary-foreground-color);
-      li a {
-        color: var(--link-foreground-color);
-      }
-    }
-  }
-}
-```
-
-And now we need to add {file}`_relatedItems.scss` in {file}`_main_.scss`:
-
-```scss
-@import 'blocks/relatedItems';
-@import 'variables';
-```
-
-## Enhancing a block schema
-
-To be able to use the Block Width widget with our Related Items block, we need to add it to the block schema.
-To do this we'll use a `schemaEnhancer`. A schema enhancer is a function that receives an object with `formData` (the block `data`), the `schema` (the original schema that we want to tweak), and the injected `intl` (to aid with internationalization).
-
-Usually we would want to keep the schema enhancers in individual files per block, after which they can be imported to the {file}`index.js`. For this example we'll leave everything in the same file:
-
-```js
-import { defineMessages } from 'react-intl';
-import { composeSchema } from '@plone/volto/helpers/Extensions';
-import { defaultStylingSchema } from '@kitconcept/volto-light-theme/components/Blocks/schema';
-import { addStyling } from '@plone/volto/helpers/Extensions/withBlockSchemaEnhancer';
-
-const messages = defineMessages({
-  BlockWidth: {
-    id: 'Block Width',
-    defaultMessage: 'Block Width',
-  },
-});
-
-const applyConfig = (config) => {
-  config.settings = {
-    ...config.settings,
-    isMultilingual: false,
-    supportedLanguages: ['en'],
-    defaultLanguage: 'en',
-  };
-
-  config.blocks.themes = [
-    {
-      style: {
-        '--theme-color': 'black',
-        '--theme-high-contrast-color': 'darkslategrey',
-        '--theme-foreground-color': 'lemonchiffon',
-        '--theme-low-contrast-foreground-color': 'lightgrey',
-      },
-      name: 'default',
-      label: 'Default',
-    },
-    {
-      style: {
-        '--theme-color': 'darkslategrey',
-        '--theme-high-contrast-color': 'black',
-        '--theme-foreground-color': 'lemonchiffon',
-        '--theme-low-contrast-foreground-color': 'lightgrey',
-      },
-      name: 'green',
-      label: 'Green',
-    },
-  ];
-
-  const relatedItemsEnhancer = ({ formData, schema, intl }) => {
-    addStyling({ schema, intl });
-
-    schema.properties.styles.schema.fieldsets[0].fields = [
-      'blockWidth:noprefix',
-      ...schema.properties.styles.schema.fieldsets[0].fields,
-    ];
-    schema.properties.styles.schema.properties['blockWidth:noprefix'] = {
-      widget: 'blockWidth',
-      title: intl.formatMessage(messages.BlockWidth),
-      default: 'default',
-      filterActions: ['narrow', 'default'],
-    };
-    return schema;
-  };
-
-  config.blocks.blocksConfig.relatedItems = {
-    ...config.blocks.blocksConfig.relatedItems,
-    schemaEnhancer: composeSchema(defaultStylingSchema, relatedItemsEnhancer),
-  };
-
-  return config;
-};
-
-export default applyConfig;
-```
-
-Finally, let's wire the width classes for our block in the file {file}`_relatedItems.scss`:
-
-```scss
-.block.relatedItems {
-    margin-right: auto;
-    margin-left: auto;
-
-  .inner-container {
-    background: var(--theme-high-contrast-color);
-    padding: 3rem;
-
-    h2.headline {
-        color: var(--primary-foreground-color);
-    }
-
-    ul {
-      color: var(--primary-foreground-color);
-      li a {
-        color: var(--link-foreground-color);
-      }
-    }
-  }
-
-  &.has--block-width--narrow {
-    max-width: var(--narrow-container-width) !important;
-  }
-
-  &.has--block-width--default {
-    max-width: var(--default-container-width) !important;
-  }
-}
-
-.block-editor-relatedItems {
-  &.has--block-width--narrow .block .block .block {
-    max-width: var(--narrow-container-width) !important;
-  }
-
-  &.has--block-width--default .block .block .block {
-    max-width: var(--default-container-width) !important;
-  }
-}
-```
-
-
-## Set themes for one block
-
-To demonstrate this feature, we'll add a custom list of themes just for the Related Items block, which will include one more theme called `Blue`. Add the property `themes` to the `relatedItems` block in the `blocksConfig` object:
-
-```js
-import { defineMessages } from 'react-intl';
-import { composeSchema } from '@plone/volto/helpers/Extensions';
-import { defaultStylingSchema } from '@kitconcept/volto-light-theme/components/Blocks/schema';
-import { addStyling } from '@plone/volto/helpers/Extensions/withBlockSchemaEnhancer';
-
-const messages = defineMessages({
-  BlockWidth: {
-    id: 'Block Width',
-    defaultMessage: 'Block Width',
-  },
-});
-
-const applyConfig = (config) => {
-  config.settings = {
-    ...config.settings,
-    isMultilingual: false,
-    supportedLanguages: ['en'],
-    defaultLanguage: 'en',
-  };
-
-  config.blocks.themes = [
-    {
-      style: {
-        '--theme-color': 'black',
-        '--theme-high-contrast-color': 'darkslategrey',
-        '--theme-foreground-color': 'lemonchiffon',
-        '--theme-low-contrast-foreground-color': 'lightgrey',
-      },
-      name: 'default',
-      label: 'Default',
-    },
-    {
-      style: {
-        '--theme-color': 'darkslategrey',
-        '--theme-high-contrast-color': 'black',
-        '--theme-foreground-color': 'lemonchiffon',
-        '--theme-low-contrast-foreground-color': 'lightgrey',
-      },
-      name: 'green',
-      label: 'Green',
-    },
-  ];
-
-  const relatedItemsEnhancer = ({ formData, schema, intl }) => {
-    addStyling({ schema, intl });
-
-    schema.properties.styles.schema.fieldsets[0].fields = [
-      'blockWidth:noprefix',
-      ...schema.properties.styles.schema.fieldsets[0].fields,
-    ];
-    schema.properties.styles.schema.properties['blockWidth:noprefix'] = {
-      widget: 'blockWidth',
-      title: intl.formatMessage(messages.BlockWidth),
-      default: 'default',
-      filterActions: ['narrow', 'default'],
-    };
-    return schema;
-  };
-
-  config.blocks.blocksConfig.relatedItems = {
-    ...config.blocks.blocksConfig.relatedItems,
-    schemaEnhancer: composeSchema(defaultStylingSchema, relatedItemsEnhancer),
-    themes: [
-      ...config.blocks.themes,
-      {
-        style: {
-          '--theme-color': 'midnightblue',
-          '--theme-high-contrast-color': 'black',
-          '--theme-foreground-color': 'lemonchiffon',
-          '--theme-low-contrast-foreground-color': 'lightgrey',
-        },
-        name: 'blue',
-        label: 'Blue',
-      },
-    ],
-  };
-
-  return config;
-};
-
-export default applyConfig;
-```
-
-## Conclusion
-
-Understanding how to extend VLT will help you take advantage of the system and quickly create consistent and flexible designs.

From f4eba8e5419f6ee1492110197934ed8c66730c78 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dante=20=C3=81lvarez?=
 <89805481+danalvrz@users.noreply.github.com>
Date: Sat, 11 Oct 2025 01:37:33 -0600
Subject: [PATCH 02/10] improve training update

---
 .../advanced-components-bm3.md                | 181 ++++++++++---
 .../block-development-widgets.md              | 108 +++-----
 .../customizing-volto-light-theme/concepts.md |  10 +-
 .../design-system-implementation.md           | 246 +++---------------
 4 files changed, 209 insertions(+), 336 deletions(-)

diff --git a/docs/customizing-volto-light-theme/advanced-components-bm3.md b/docs/customizing-volto-light-theme/advanced-components-bm3.md
index b90172a9d..221f8f915 100644
--- a/docs/customizing-volto-light-theme/advanced-components-bm3.md
+++ b/docs/customizing-volto-light-theme/advanced-components-bm3.md
@@ -7,9 +7,9 @@ myst:
     "keywords": "Plone, Volto, Training, Volto Light Theme, Integrate, block"
 ---
 
-# 4. Advanced Components, Site Customization & Block Model v3
+# Advanced Components, Site Customization & Block Model v3
 
-## 4.1 Understanding the Card Primitive
+## Understanding the Card Primitive
 
 The Card primitive is VLT's reusable component for displaying content in card layouts. It has three configurable slots: image, summary, and actions.
 
@@ -69,7 +69,7 @@ const Summary = config.getComponent({
 </Card.Summary>
 ```
 
-## 4.2 Creating Custom Summary Components
+## Creating Custom Summary Components
 
 The Summary component displays content metadata in listings, teasers, and cards. VLT includes built-in implementations:
 
@@ -97,13 +97,19 @@ First, create a custom "Product" content type through the Plone UI:
 
 ### Step 2: Create a Custom Summary Component
 
-Create `src/components/Summary/ProductSummary.jsx`:
+Create `src/components/Summary/ProductSummary.tsx`:
 
-```jsx
+```tsx
 import { FormattedNumber } from 'react-intl';
 
-const ProductSummary = ({ item, HeadingTag = 'h3' }) => {
-  const { title, description, head_title, currency = 'EUR' } = item;
+const ProductSummary = ({ item }) => {
+  const {
+    title,
+    description,
+    HeadingTag = 'h3',
+    head_title,
+    currency = 'EUR',
+  } = item;
   const price = parseFloat(head_title);
 
   return (
@@ -142,9 +148,7 @@ Create `src/theme/_productSummary.scss`:
   padding-bottom: 0 !important;
   .product-price {
     font-size: 1.25rem;
-    font-weight: var(--font-bold);
     color: var(--accent-color);
-    margin-bottom: 0.5rem;
     margin-top: 0.5rem;
 
     .price {
@@ -196,7 +200,7 @@ export default function install(config: ConfigType) {
 3. Add the Product to a Listing or Teaser block
 4. The custom ProductSummary will display the price, title, and description
 
-## 4.3 Creating Custom Listing Variations with Card Actions
+## Creating Custom Listing Variations with Card Actions
 
 Listing variations customize content display in Listing blocks. Let's create a ProductTemplate demonstrating the Card.Actions slot for interactive buttons.
 
@@ -209,9 +213,9 @@ The Card.Actions slot provides interactive elements beyond the main card link:
 
 ### Step 1: Create ProductActions Component
 
-Create `src/components/Actions/ProductAction.jsx`:
+Create `src/components/Actions/ProductActions.tsx`:
 
-```jsx
+```tsx
 const ProductActions = ({ item }) => {
   return (
     <>
@@ -228,7 +232,7 @@ export default ProductActions;
 Update `src/config/settings.ts`:
 
 ```typescript
-import ProductActions from '../components/Actions/ProductAction';
+import ProductActions from '../components/Actions/ProductActions';
 
 export default function install(config: ConfigType) {
   // ... previous configuration ...
@@ -246,9 +250,9 @@ export default function install(config: ConfigType) {
 
 ### Step 3: Create ProductTemplate Listing Variation
 
-Create `src/components/blocks/Listing/ProductTemplate.jsx`:
+Create `src/components/blocks/Listing/ProductTemplate.tsx`:
 
-```jsx
+```tsx
 import React from 'react';
 import PropTypes from 'prop-types';
 import ConditionalLink from '@plone/volto/components/manage/ConditionalLink/ConditionalLink';
@@ -369,24 +373,126 @@ Create `src/theme/blocks/_listing.scss`:
 ```scss
 .block.listing {
   &.products {
+    max-width: var(--default-container-width) !important;
+    &.next--has--same--backgroundColor.next--is--same--block-type,
+    &.next--is--__button {
+      .listing-item:last-child {
+        padding-bottom: 0 !important;
+        border-bottom: none !important;
+      }
+    }
+
     .items {
-      display: grid;
-      grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
-      gap: 2rem;
+      display: flex;
+      flex-wrap: wrap;
+      @media only screen and (max-width: $largest-mobile-screen) {
+        flex-direction: column;
+
+        .listing-item {
+          padding-bottom: 20px !important;
+        }
+      }
+    }
+    .headline {
+      @include block-title();
+      margin-right: 0 !important;
+      margin-left: 0 !important;
+    }
+    .listing-item {
+      align-items: normal;
+      border-bottom: none;
+      margin: 0 !important;
+
+      @media only screen and (min-width: $tablet-breakpoint) {
+        width: 50%;
+        padding-top: 10px;
+        padding-bottom: 10px !important;
+
+        &:nth-child(2n) {
+          padding-left: 10px !important;
+        }
+
+        &:nth-child(2n + 1) {
+          padding-right: 10px !important;
+        }
+
+        &:last-child,
+        &:nth-last-child(2):not(:nth-child(2n)) {
+          padding-bottom: 0 !important;
+        }
+
+        &:first-child,
+        &:nth-child(2) {
+          padding-top: 0 !important;
+        }
+      }
+
+      &:last-child:nth-child(2n + 1) {
+        @media only screen and (min-width: $largest-mobile-screen) {
+          margin-left: 0 !important;
+        }
+      }
 
       .card {
-        .card-actions {
-          padding: 1rem;
-          border-top: 1px solid var(--theme-high-contrast-color);
+        flex-grow: 1;
+        .card-inner {
+          background: var(--theme-high-contrast-color);
+          .image-wrapper {
+            img {
+              width: 100%;
+              margin: 0;
+              aspect-ratio: var(--image-aspect-ratio, $aspect-ratio) !important;
+            }
+          }
+          .card-summary {
+            padding: 0 $spacing-large $spacing-large $spacing-large;
+            margin-top: $spacing-medium;
+
+            .headline {
+              padding: 0 !important;
+              margin-bottom: $spacing-small;
+              letter-spacing: 1px;
+              text-transform: uppercase;
+              @include headtitle1();
+              @include word-break();
+            }
+
+            h2 {
+              margin: 0 0 $spacing-small 0;
+              @include text-heading-h3();
+            }
+            p {
+              margin-bottom: 0;
+              @include body-text();
+            }
+            p:empty {
+              display: none;
+            }
+          }
+
+          .product-price {
+            display: flex;
+            justify-content: end;
+            padding: $spacing-small;
 
-          .add-to-cart {
-            width: 100%;
+            .price {
+              font-size: 2.5rem;
+              width: 30%;
+            }
+          }
+        }
+
+        .actions-wrapper {
+          display: flex;
+          justify-content: end;
+          padding: 0 $spacing-large $spacing-medium $spacing-large;
+          .rent-now-button {
+            width: 30%;
             padding: 0.75rem 1rem;
+            margin: 1rem;
             background-color: var(--accent-color);
-            color: var(--accent-foreground-color);
+            color: white;
             border: none;
-            border-radius: 4px;
-            font-weight: var(--font-bold);
             cursor: pointer;
             transition: opacity 0.2s;
 
@@ -419,7 +525,7 @@ Import in `src/theme/_main.scss`:
 4. Configure to show Product content type
 5. Products display with image, summary, and "Get now" button
 
-## 4.4 Working with Slots
+## Working with Slots
 
 VLT provides slots for extending the layout without component shadowing. Let's create a practical example: a newsletter signup component in the preFooter slot.
 
@@ -436,9 +542,9 @@ VLT provides slots for extending the layout without component shadowing. Let's c
 
 ### Step 1: Create Newsletter Signup Component
 
-Create `src/components/NewsletterSignup/NewsletterSignup.jsx`:
+Create `src/components/NewsletterSignup/NewsletterSignup.tsx`:
 
-```jsx
+```tsx
 import React, { useState } from 'react';
 
 const NewsletterSignup = () => {
@@ -499,7 +605,6 @@ Create `src/theme/_newsletterSignup.scss`:
   .newsletter-title {
     font-size: 2rem;
     margin-bottom: 1rem;
-    font-weight: var(--font-bold);
   }
 
   .newsletter-description {
@@ -537,7 +642,6 @@ Create `src/theme/_newsletterSignup.scss`:
       color: var(--accent-foreground-color);
       border: none;
       font-size: 1rem;
-      font-weight: var(--font-bold);
       cursor: pointer;
       transition: opacity 0.2s;
 
@@ -587,7 +691,7 @@ export default function install(config: ConfigType) {
 
 The newsletter signup component will now appear before the footer on all pages, demonstrating how slots enable you to extend the layout without shadowing core components.
 
-## 4.5 Site Customization Behaviors
+## Site Customization Behaviors
 
 VLT provides backend behaviors for site customization that you activated earlier. These behaviors enable fields for customizing the site without code changes.
 
@@ -614,7 +718,7 @@ Through the Plone UI, you can customize:
 - **Footer logos**: List of logos with links and customizable size (small/large) and container width (default/layout)
 - **Footer colophon text**: Customizable last line of footer
 
-## 4.6 Block Model v3 (opt-in)
+## Block Model v3 (opt-in)
 
 ```{note}
 Block Model v3 is a beta feature. It's recommended to only use it when all blocks in your registry are v3-compatible (indicated by banner in block's GitHub repository).
@@ -670,14 +774,15 @@ In your project's `src/config/settings.ts`:
 
 ```typescript
 export default function install(config: ConfigType) {
-  // Enable Block Model v3 globally
+  // Enable Block Model v3
   config.settings.blockModel = 3;
-
+  config.blocks.blocksConfig.slate.blockModel = config.settings.blockModel;
+  config.blocks.blocksConfig.title.blockModel = config.settings.blockModel;
+  config.blocks.blocksConfig.__button.blockModel = config.settings.blockModel;
   // Define block categories for spacing
   config.blocks.blocksConfig.slate.category = 'inline';
   config.blocks.blocksConfig.title.category = 'title';
   config.blocks.blocksConfig.__button.category = 'action';
-  config.blocks.blocksConfig.gridBlock.category = 'cards';
 
   return config;
 }
@@ -694,7 +799,7 @@ Vertical spacing between blocks is provided by the **upper block**:
 
 ### View Mode Structure
 
-```jsx
+```tsx
 <div
   style="$StyleWrapperStyles"
   className="block $type category-$category $StyleWrapperClassNames"
@@ -707,7 +812,7 @@ Vertical spacing between blocks is provided by the **upper block**:
 
 ### Edit Mode Structure
 
-```jsx
+```tsx
 <div
   style="$StyleWrapperStyles"
   className="block $type category-$category $StyleWrapperClassNames"
diff --git a/docs/customizing-volto-light-theme/block-development-widgets.md b/docs/customizing-volto-light-theme/block-development-widgets.md
index a363ee1fa..d1f010bd5 100644
--- a/docs/customizing-volto-light-theme/block-development-widgets.md
+++ b/docs/customizing-volto-light-theme/block-development-widgets.md
@@ -7,9 +7,9 @@ myst:
     "keywords": "Plone, Volto, Training, Volto Light Theme"
 ---
 
-# 3. Block Development, Widgets & Integration
+# Block Development, Widgets & Integration
 
-## 3.1 Understanding VLT Widgets
+## Understanding VLT Widgets
 
 VLT provides powerful widgets for block configuration that work with the StyleWrapper system.
 
@@ -61,13 +61,13 @@ Allows introducing a list of ordered objects with drag and drop:
 }
 ```
 
-## 3.2 Creating a Custom Hero Block
+## Creating a Custom Hero Block
 
 Let's build a hero block step by step, starting with a basic implementation and then enhancing it with VLT widgets.
 
 ### Step 1: Create Basic Block Schema
 
-Create `src/components/blocks/myHero/schema.js`:
+Create `src/components/blocks/myHero/schema.ts`:
 
 ```javascript
 import { defineMessages } from 'react-intl';
@@ -133,35 +133,35 @@ export { heroBlockSchema };
 
 ### Step 2: Create View Component
 
-Create `src/components/blocks/myHero/View.jsx`:
+Create `src/components/blocks/myHero/View.tsx`:
 
-```jsx
+```tsx
 import React from 'react';
-import { withBlockExtensions } from '@plone/volto/helpers';
 import cx from 'classnames';
 import config from '@plone/volto/registry';
 import { flattenToAppURL, isInternalURL } from '@plone/volto/helpers/Url/Url';
+import type { BlockViewProps } from '@plone/types';
 
-const HeroView = (props) => {
-  const { data, className, style } = props;
-  const { title, subtitle, backgroundImage } = data;
+const HeroView = (props: BlockViewProps) => {
+  const { className, style } = props;
+  const { title, subtitle, backgroundImage, image_scales, url } = props?.data;
 
   let renderedImage = null;
-  if (data.backgroundImage) {
+  if (backgroundImage) {
     let Image = config.getComponent('Image').component;
     if (Image) {
       renderedImage = (
         <Image
           item={
-            data.backgroundImage
+            backgroundImage
               ? {
-                  '@id': data.backgroundImage[0]['@id'],
-                  image_field: data.backgroundImage[0].image_field,
-                  image_scales: data.backgroundImage[0].image_scales,
+                  '@id': backgroundImage[0]['@id'],
+                  image_field: backgroundImage[0].image_field,
+                  image_scales: backgroundImage[0].image_scales,
                 }
               : null
           }
-          src={!data.image_scales ? data.url : null}
+          src={!image_scales ? url : null}
           alt=""
           loading="lazy"
           responsive={true}
@@ -171,9 +171,9 @@ const HeroView = (props) => {
       renderedImage = (
         <img
           src={
-            isInternalURL(data.url['@id'])
-              ? `${flattenToAppURL(data.url['@id'])}/@@images/image`
-              : data.url['@id']
+            isInternalURL(url['@id'])
+              ? `${flattenToAppURL(url['@id'])}/@@images/image`
+              : url['@id']
           }
           alt=""
           loading="lazy"
@@ -186,8 +186,8 @@ const HeroView = (props) => {
     <div style={style} className={cx('block hero', className)}>
       <div className="hero-content">
         <div className="hero-text">
-          {title && <h1 className="hero-title">{title}</h1>}
-          {subtitle && <p className="hero-subtitle">{subtitle}</p>}
+          {title && <h1 className="hero-title">{title as any}</h1>}
+          {subtitle && <p className="hero-subtitle">{subtitle as any}</p>}
         </div>
 
         {backgroundImage && (
@@ -198,7 +198,7 @@ const HeroView = (props) => {
   );
 };
 
-export default withBlockExtensions(HeroView);
+export default HeroView;
 ```
 
 ### Step 3: Create Edit Component
@@ -252,7 +252,7 @@ Update `src/config/blocks.ts`:
 import type { ConfigType } from '@plone/registry';
 import HeroView from '../components/blocks/myHero/View';
 import HeroEdit from '../components/blocks/myHero/Edit';
-import { heroBlockSchema } from '../components/blocks/myHero/schema.js';
+import { heroBlockSchema } from '../components/blocks/myHero/schema';
 import heroSVG from '@plone/volto/icons/hero.svg';
 
 export default function install(config: ConfigType) {
@@ -309,14 +309,12 @@ Create `src/theme/blocks/_hero.scss`:
 
       .hero-title {
         font-size: 5rem;
-        font-weight: var(--font-bold);
-        margin-bottom: var(--space-3);
+        margin-bottom: $spacing-small;
         line-height: 1;
       }
 
       .hero-subtitle {
         font-size: 3rem;
-        margin-bottom: var(--space-6);
         opacity: 0.95;
         line-height: 1;
       }
@@ -443,7 +441,7 @@ import HeroEdit from '../components/blocks/myHero/Edit';
 import {
   heroBlockSchema,
   heroSchemaEnhancer,
-} from '../components/blocks/myHero/schema.js';
+} from '../components/blocks/myHero/schema';
 import { composeSchema } from '@plone/volto/helpers/Extensions';
 import { defaultStylingSchema } from '@kitconcept/volto-light-theme/components/Blocks/schema';
 import heroSVG from '@plone/volto/icons/hero.svg';
@@ -509,14 +507,12 @@ Update `src/theme/blocks/_hero.scss` to use the CSS custom properties set by the
 
       .hero-title {
         font-size: 5rem;
-        font-weight: var(--font-bold);
-        margin-bottom: var(--space-3);
+        margin-bottom: $spacing-small;
         line-height: 1;
       }
 
       .hero-subtitle {
         font-size: 3rem;
-        margin-bottom: var(--space-6);
         opacity: 0.95;
         line-height: 1;
       }
@@ -525,12 +521,14 @@ Update `src/theme/blocks/_hero.scss` to use the CSS custom properties set by the
 }
 ```
 
-## 3.3 Integrating Third-Party Blocks
+## Integrating Third-Party Blocks
 
 Let's learn how to integrate the `@plone-collective/volto-relateditems-block` into VLT.
 
 ### Install the Block
 
+To install the related items block, make sure you are in the `frontend/packages/volto-my-project` folder, and use the following command:
+
 ```bash
 pnpm install @plone-collective/volto-relateditems-block@latest
 ```
@@ -553,52 +551,15 @@ Add it to your `package.json` addons (before VLT):
 
 ### Enhance the Block Schema
 
-To add the Block Width widget to the Related Items block, create a schema enhancer file.
-
-Create `src/components/blocks/relatedItems/schemaEnhancer.js`:
-
-```javascript
-import { defineMessages } from 'react-intl';
-
-const messages = defineMessages({
-  blockWidth: {
-    id: 'Block Width',
-    defaultMessage: 'Block Width',
-  },
-});
-
-const relatedItemsSchemaEnhancer = ({ formData, schema, intl }) => {
-  schema.properties.styles.schema.fieldsets[0].fields = [
-    'blockWidth:noprefix',
-    ...schema.properties.styles.schema.fieldsets[0].fields,
-  ];
-
-  schema.properties.styles.schema.properties['blockWidth:noprefix'] = {
-    widget: 'blockWidth',
-    title: intl.formatMessage(messages.blockWidth),
-    default: 'default',
-    filterActions: ['narrow', 'default'],
-  };
-
-  return schema;
-};
-
-export default relatedItemsSchemaEnhancer;
-```
-
-Then update `src/config/blocks.ts` to register the enhancer:
+To add the theme feature to the Related Items block, update `src/config/blocks.ts` to register the `defaultStylingSchema` enhancer:
 
 ```typescript
-import { composeSchema } from '@plone/volto/helpers/Extensions';
-import { defaultStylingSchema } from '@kitconcept/volto-light-theme/components/Blocks/schema';
-import relatedItemsSchemaEnhancer from '../components/blocks/relatedItems/schemaEnhancer';
-
 export default function install(config: ConfigType) {
   // ... previous configuration ...
 
   config.blocks.blocksConfig.relatedItems = {
     ...config.blocks.blocksConfig.relatedItems,
-    schemaEnhancer: composeSchema(defaultStylingSchema, relatedItemsSchemaEnhancer),
+    schemaEnhancer: defaultStylingSchema,
   };
 
   return config;
@@ -611,13 +572,10 @@ Create `src/theme/blocks/_relatedItems.scss`:
 
 ```scss
 .block.relatedItems {
-  max-width: var(--block-width);
-  margin-right: auto;
-  margin-left: auto;
-
   .inner-container {
     background: var(--theme-high-contrast-color);
     padding: 3rem;
+    width: var(--narrow-container-width);
 
     h2.headline {
       color: var(--theme-foreground-color);
@@ -630,8 +588,6 @@ Create `src/theme/blocks/_relatedItems.scss`:
       }
     }
   }
-
-
 }
 
 ```
diff --git a/docs/customizing-volto-light-theme/concepts.md b/docs/customizing-volto-light-theme/concepts.md
index 70ef7e4cd..f324158d9 100644
--- a/docs/customizing-volto-light-theme/concepts.md
+++ b/docs/customizing-volto-light-theme/concepts.md
@@ -6,9 +6,9 @@ myst:
     "property=og:title": "Foundation, Concepts & Project Setup"
     "keywords": "Plone, Volto, Training, Volto Light Theme"
 ---
-# 1. Foundation, Concepts & Project Setup
+# Foundation, Concepts & Project Setup
 
-## 1.1 Volto Light Theme Core Concepts
+## Volto Light Theme Core Concepts
 
 Volto Light Theme (VLT) is a customizable theme built for the Volto frontend of the Plone CMS. It provides a foundation that aims to solve many common design challenges, while remaining flexible enough for customization. It's particularly valuable because it is based on real-world experience, while simultaneously embodying the Volto vision for the future. This module will help you understand the core concepts in VLT and create a mental map of its parts.
 
@@ -139,11 +139,11 @@ The `BlockAlignmentWidget` takes advantage of the StyleWrapper by setting the `-
 --align-right: end;
 ```
 
-## 1.2 Create a New Project with Cookieplone
+## Create a New Project with Cookieplone
 
 We recommend creating your Plone project with **Cookieplone**. Our comprehensive documentation provides step-by-step guidance to help you get started. For detailed installation instructions, visit our [Cookieplone guide](https://6.docs.plone.org/install/create-project-cookieplone.html).
 
-## 1.3 Installing Volto Light Theme
+## Installing Volto Light Theme
 
 ### Step 1: Install VLT and Recommended Block Add-ons
 
@@ -252,7 +252,7 @@ To enable site customization through the UI:
 
 Now your project should have the VLT Site configurations available.
 
-## 1.4 File Structure Setup
+## File Structure Setup
 
 Let's set up the recommended file structure. In your project add-on's `src` folder, create the following structure:
 
diff --git a/docs/customizing-volto-light-theme/design-system-implementation.md b/docs/customizing-volto-light-theme/design-system-implementation.md
index 71cabcf3e..eaadd9aa3 100644
--- a/docs/customizing-volto-light-theme/design-system-implementation.md
+++ b/docs/customizing-volto-light-theme/design-system-implementation.md
@@ -7,9 +7,9 @@ myst:
     "keywords": "Plone, Volto, Training, Theme, Footer"
 ---
 
-# 2. Design System Implementation & Theming
+# Design System Implementation & Theming
 
-## 2.1 Extracting Design Tokens
+## Extracting Design Tokens
 
 When working with a given design, systematically extract design decisions. Identify:
 
@@ -38,13 +38,26 @@ Look for:
 - Font weights
 
 
-## 2.2 Implementing Your Design System
+## Implementing Your Design System
 
 VLT has migrated to use standardized color definitions. These use CSS properties that are injected at runtime in the right places, so your CSS can adapt to use them generically. The resulting CSS is simpler, and there's no need to define class names for each color definition.
 
-### Step 1: Create _site.scss
+### Step 1: Add Font Files
 
-In `src/theme/_site.scss`, define your color variables and custom properties:
+If you're using custom fonts, add the font files to your theme directory. Create a `fonts` folder in your theme directory and place your font files there:
+
+```
+src/theme/fonts/Chakra_Petch/
+  ├── ChakraPetch-Regular.ttf
+  ├── ChakraPetch-Bold.ttf
+  └── ... (other font weights/styles)
+```
+
+This ensures the font files are bundled with your theme and can be referenced in your SCSS files.
+
+### Step 2: Create _site.scss
+
+In `src/theme/_site.scss`, define your color variables, custom properties and block-specific styles:
 
 ```scss
 @font-face {
@@ -181,7 +194,7 @@ In `src/theme/_site.scss`, define your color variables and custom properties:
 }
 ```
 
-### Step 2: Configure Block Themes
+### Step 3: Configure Block Themes
 
 In `src/config/blocks.ts`, define block themes:
 
@@ -203,133 +216,14 @@ export default function install(config: ConfigType) {
     },
     {
       style: {
-        '--theme-color': `/* White edge bleed for continuity */
-                linear-gradient(180deg,
-                    rgba(255, 255, 255, 0.9) 0%,
-                    rgba(255, 255, 255, 0.6) 8%,
-                    rgba(255, 255, 255, 0.3) 12%,
-                    transparent 18%,
-                    transparent 82%,
-                    rgba(255, 255, 255, 0.3) 88%,
-                    rgba(255, 255, 255, 0.6) 92%,
-                    rgba(255, 255, 255, 0.9) 100%),
-
-                /* Top white highlights - asymmetric cluster */
-                radial-gradient(ellipse 900px 650px at 12% 8%,
-                    rgba(255, 255, 255, 0.38) 0%,
-                    rgba(243, 251, 251, 0.26) 28%,
-                    rgba(228, 244, 244, 0.14) 52%,
-                    transparent 72%),
-
-                radial-gradient(ellipse 750px 850px at 6% 22%,
-                    rgba(255, 255, 255, 0.34) 0%,
-                    rgba(238, 249, 249, 0.2) 32%,
-                    rgba(220, 240, 240, 0.1) 58%,
-                    transparent 78%),
-
-                radial-gradient(ellipse 820px 580px at 88% 12%,
-                    rgba(255, 255, 255, 0.42) 0%,
-                    rgba(246, 252, 252, 0.28) 30%,
-                    rgba(232, 246, 246, 0.15) 54%,
-                    transparent 74%),
-
-                /* Bottom white highlights - dispersed asymmetrically */
-                radial-gradient(ellipse 980px 620px at 82% 88%,
-                    rgba(255, 255, 255, 0.4) 0%,
-                    rgba(244, 251, 251, 0.27) 26%,
-                    rgba(230, 245, 245, 0.13) 50%,
-                    transparent 73%),
-
-                radial-gradient(ellipse 680px 780px at 18% 90%,
-                    rgba(255, 255, 255, 0.35) 0%,
-                    rgba(240, 250, 250, 0.22) 34%,
-                    rgba(225, 242, 242, 0.11) 60%,
-                    transparent 80%),
-
-                radial-gradient(ellipse 720px 520px at 68% 94%,
-                    rgba(255, 255, 255, 0.3) 0%,
-                    rgba(235, 247, 247, 0.17) 38%,
-                    transparent 68%),
-
-                /* Color hotspot 1 - upper right quadrant */
-                radial-gradient(ellipse 850px 750px at 70% 35%,
-                    rgba(175, 202, 200, 0.5) 0%,
-                    rgba(180, 206, 204, 0.38) 25%,
-                    rgba(190, 212, 210, 0.24) 45%,
-                    rgba(200, 220, 218, 0.12) 65%,
-                    transparent 85%),
-
-                /* Color hotspot 2 - lower left quadrant */
-                radial-gradient(ellipse 920px 800px at 25% 65%,
-                    rgba(165, 195, 193, 0.45) 0%,
-                    rgba(175, 202, 200, 0.34) 28%,
-                    rgba(185, 210, 208, 0.22) 50%,
-                    rgba(195, 215, 213, 0.11) 70%,
-                    transparent 87%),
-
-                /* Color hotspot 3 - center right */
-                radial-gradient(circle 700px at 78% 52%,
-                    rgba(170, 198, 196, 0.42) 0%,
-                    rgba(180, 205, 203, 0.3) 30%,
-                    rgba(192, 214, 212, 0.18) 55%,
-                    rgba(205, 222, 220, 0.09) 75%,
-                    transparent 90%),
-
-                /* Organic flow connecting hotspots */
-                radial-gradient(ellipse 1100px 900px at 45% 48%,
-                    rgba(175, 202, 200, 0.28) 0%,
-                    rgba(185, 210, 208, 0.18) 35%,
-                    rgba(195, 216, 214, 0.1) 60%,
-                    rgba(205, 222, 220, 0.05) 78%,
-                    transparent 90%),
-
-                /* Additional scattered color pockets */
-                radial-gradient(circle 550px at 15% 40%,
-                    rgba(172, 198, 196, 0.32) 0%,
-                    rgba(182, 207, 205, 0.2) 38%,
-                    rgba(195, 216, 214, 0.1) 68%,
-                    transparent 85%),
-
-                radial-gradient(ellipse 680px 580px at 88% 68%,
-                    rgba(178, 203, 201, 0.35) 0%,
-                    rgba(188, 210, 208, 0.22) 35%,
-                    rgba(200, 218, 216, 0.11) 65%,
-                    transparent 82%),
-
-                radial-gradient(ellipse 620px 720px at 52% 28%,
-                    rgba(168, 196, 194, 0.3) 0%,
-                    rgba(180, 205, 203, 0.18) 40%,
-                    rgba(195, 215, 213, 0.08) 70%,
-                    transparent 88%),
-
-                radial-gradient(circle 480px at 35% 78%,
-                    rgba(175, 200, 198, 0.28) 0%,
-                    rgba(188, 210, 208, 0.15) 42%,
-                    transparent 75%),
-
-                /* Asymmetrical accent flows */
-                conic-gradient(from 125deg at 28% 44%,
-                    transparent 0deg,
-                    rgba(178, 203, 201, 0.18) 48deg,
-                    rgba(185, 210, 208, 0.14) 95deg,
-                    transparent 145deg,
-                    rgba(172, 198, 196, 0.12) 235deg,
-                    transparent 285deg),
-
-                /* Base gradient foundation - subtle */
-                linear-gradient(182deg,
-                    #ffffff 0%,
-                    #f9fcfc 10%,
-                    #ebf4f3 22%,
-                    #d8e6e5 35%,
-                    #c5d8d6 45%,
-                    #b8cece 52%,
-                    #c5d8d6 59%,
-                    #d8e6e5 69%,
-                    #ebf4f3 82%,
-                    #f9fcfc 92%,
-                    #ffffff 100%)`,
-        '--theme-high-contrast-color': 'rgba(255, 255, 255, 0.1)',
+        '--theme-color': `linear-gradient(180deg, oklab(1 0 0 / 0.9) 0%, transparent 15%, transparent 85%, oklab(1 0 0 / 0.9) 100%),
+                radial-gradient(ellipse 850px 700px at 12% 15%, oklab(1 0 0 / 0.4) 0%, transparent 70%),
+                radial-gradient(ellipse 900px 650px at 85% 85%, oklab(1 0 0 / 0.4) 0%, transparent 70%),
+                radial-gradient(ellipse 850px 750px at 70% 35%, oklab(0.805 -0.030 -0.003 / 0.5) 0%, oklab(0.835 -0.025 -0.002 / 0.2) 50%, transparent 85%),
+                radial-gradient(ellipse 920px 800px at 25% 65%, oklab(0.780 -0.032 -0.004 / 0.45) 0%, oklab(0.825 -0.027 -0.003 / 0.2) 50%, transparent 87%),
+                radial-gradient(ellipse 1100px 900px at 50% 50%, oklab(0.805 -0.030 -0.003 / 0.25) 0%, oklab(0.850 -0.025 -0.002 / 0.1) 60%, transparent 90%),
+                linear-gradient(182deg, oklab(1 0 0) 0%, oklab(0.988 -0.006 0) 10%, oklab(0.958 -0.016 -0.001) 22%, oklab(0.910 -0.025 -0.003) 35%, oklab(0.860 -0.030 -0.003) 45%, oklab(0.820 -0.032 -0.004) 52%, oklab(0.860 -0.030 -0.003) 59%, oklab(0.910 -0.025 -0.003) 69%, oklab(0.958 -0.016 -0.001) 82%, oklab(0.988 -0.006 0) 92%, oklab(1 0 0) 100%)`,
+        '--theme-high-contrast-color': 'oklab(1 0 0 / 0.1)',
         '--theme-foreground-color': 'black',
         '--theme-low-contrast-foreground-color': '#555555',
       },
@@ -342,26 +236,6 @@ export default function install(config: ConfigType) {
 }
 ```
 
-### Step 3: Configure Settings
-
-In `src/config/settings.ts`:
-
-```typescript
-import type { ConfigType } from '@plone/registry';
-import installBlocks from './blocks';
-
-export default function install(config: ConfigType) {
-  // Language settings
-  config.settings.isMultilingual = false;
-  config.settings.supportedLanguages = ['en'];
-  config.settings.defaultLanguage = 'en';
-
-  installBlocks(config);
-
-  return config;
-}
-```
-
 ### Step 4: Main Index Configuration
 
 In `src/index.ts`:
@@ -369,9 +243,11 @@ In `src/index.ts`:
 ```typescript
 import type { ConfigType } from '@plone/registry';
 import installSettings from './config/settings';
+import installBlocks from './config/blocks';
 
 function applyConfig(config: ConfigType) {
   installSettings(config);
+  installBlocks(config);
   return config;
 }
 
@@ -386,68 +262,4 @@ In `src/theme/_main.scss`:
 @import './site';
 ```
 
-## 2.3 Customizing Block Styles
-
-Let's add custom styles for specific blocks. In your `_site.scss`, add block-specific styles:
-
-```scss
-:root {
-  // ... previous variables ...
-
-  #page-document {
-    .block {
-      &.__button {
-        .button {
-          button {
-            padding: 1rem;
-          }
-        }
-      }
-
-      &.__button {
-        .ui.button:hover {
-          --theme-color: white;
-        }
-      }
-
-      &.slider {
-        .teaser-item-title {
-          background: rgba(255, 255, 255, 0.1);
-          color: var(--theme-foreground-color) !important;
-          backdrop-filter: blur(20px) saturate(110%);
-          -webkit-backdrop-filter: blur(20px) saturate(180%);
-          box-shadow:
-            0 8px 32px 0 rgba(31, 135, 125, 0.1),
-            inset 0 0 0 1px rgba(255, 255, 255, 0.1);
-        }
-      }
-
-      &.gridBlock {
-        .four {
-          .slate {
-            padding: 2.5rem;
-            padding-top: 4rem !important;
-            backdrop-filter: blur(20px) saturate(110%);
-            -webkit-backdrop-filter: blur(20px) saturate(180%);
-            box-shadow:
-              0 8px 32px 0 rgba(31, 135, 125, 0.1),
-              inset 0 0 0 1px rgba(255, 255, 255, 0.1);
-          }
-        }
-      }
-
-      &.teaser {
-        .card {
-          .card-inner {
-            .card-summary {
-              padding: $spacing-large;
-            }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
 ---
\ No newline at end of file

From 451922af406cb04c0eec97218d6b8269c0dda358 Mon Sep 17 00:00:00 2001
From: iRohitSingh <isinghrohit0@gmail.com>
Date: Sun, 12 Oct 2025 21:33:00 +0300
Subject: [PATCH 03/10] Fix code and css

---
 .../block-development-widgets.md              | 124 +++++++++++-------
 .../customizing-volto-light-theme/concepts.md |   2 +-
 2 files changed, 79 insertions(+), 47 deletions(-)

diff --git a/docs/customizing-volto-light-theme/block-development-widgets.md b/docs/customizing-volto-light-theme/block-development-widgets.md
index d1f010bd5..30b21f7c3 100644
--- a/docs/customizing-volto-light-theme/block-development-widgets.md
+++ b/docs/customizing-volto-light-theme/block-development-widgets.md
@@ -144,36 +144,35 @@ import type { BlockViewProps } from '@plone/types';
 
 const HeroView = (props: BlockViewProps) => {
   const { className, style } = props;
-  const { title, subtitle, backgroundImage, image_scales, url } = props?.data;
+  const { title, subtitle, backgroundImage, url } = props?.data || {};
+
+  const hasImage = backgroundImage?.[0]?.['@id'];
 
   let renderedImage = null;
-  if (backgroundImage) {
-    let Image = config.getComponent('Image').component;
+  if (hasImage) {
+    const Image = config.getComponent('Image').component;
+    const imageItem = backgroundImage[0];
+
     if (Image) {
       renderedImage = (
         <Image
-          item={
-            backgroundImage
-              ? {
-                  '@id': backgroundImage[0]['@id'],
-                  image_field: backgroundImage[0].image_field,
-                  image_scales: backgroundImage[0].image_scales,
-                }
-              : null
-          }
-          src={!image_scales ? url : null}
+          item={{
+            '@id': imageItem['@id'],
+            image_field: imageItem.image_field,
+            image_scales: imageItem.image_scales,
+          }}
           alt=""
           loading="lazy"
-          responsive={true}
+          responsive
         />
       );
     } else {
       renderedImage = (
         <img
           src={
-            isInternalURL(url['@id'])
+            isInternalURL(url?.['@id'])
               ? `${flattenToAppURL(url['@id'])}/@@images/image`
-              : url['@id']
+              : url?.['@id']
           }
           alt=""
           loading="lazy"
@@ -183,16 +182,17 @@ const HeroView = (props: BlockViewProps) => {
   }
 
   return (
-    <div style={style} className={cx('block hero', className)}>
+    <div
+      className={cx('block hero', className, { 'has-image': hasImage })}
+      style={style}
+    >
+      {hasImage && <div className="hero-image-wrapper">{renderedImage}</div>}
+
       <div className="hero-content">
         <div className="hero-text">
-          {title && <h1 className="hero-title">{title as any}</h1>}
-          {subtitle && <p className="hero-subtitle">{subtitle as any}</p>}
+          {title && <h1 className="hero-title">{title}</h1>}
+          {subtitle && <p className="hero-subtitle">{subtitle}</p>}
         </div>
-
-        {backgroundImage && (
-          <div className="hero-image-wrapper">{renderedImage}</div>
-        )}
       </div>
     </div>
   );
@@ -285,40 +285,72 @@ Create `src/theme/blocks/_hero.scss`:
 .block.hero {
   position: relative;
   display: flex;
+  width: var(--default-container-width);
+  max-width: var(--block-width) !important;
   align-items: center;
   justify-content: center;
-  background-size: cover;
-  background-position: center;
+  background-color: var(--theme-color);
+  color: var(--theme-foreground-color);
+  margin-inline: auto;
 
+  // default text view
   .hero-content {
-    .hero-image-wrapper {
-      img {
-        aspect-ratio: var(--image-aspect-ratio, 16/9);
-        opacity: 0.8;
-      }
+    position: relative;
+    z-index: 1;
+    width: 100%;
+  }
+
+  .hero-text {
+    display: flex;
+    width: 100%;
+    height: 100%;
+    flex-direction: column;
+    align-items: var(--align--block-alignment);
+    gap: 1rem;
+    text-align: var(--align--block-alignment);
+
+    .hero-title {
+      margin-bottom: $spacing-small;
+      font-size: 5rem;
+      line-height: 1.1;
     }
 
-    .hero-text {
+    .hero-subtitle {
+      margin-bottom: $spacing-small;
+      font-size: 2rem;
+      line-height: 1.3;
+      opacity: 0.9;
+    }
+  }
+
+  // has-image version
+  &.has-image {
+    color: #fff;
+
+    .hero-image-wrapper {
       position: absolute;
-      display: flex;
-      flex-direction: column;
-      width: 100%;
-      height: 100%;
-      padding: 4rem;
-      z-index: 2;
+      z-index: 0;
+      inset: 0;
 
-      .hero-title {
-        font-size: 5rem;
-        margin-bottom: $spacing-small;
-        line-height: 1;
+      img {
+        width: 100%;
+        height: 100%;
+        object-fit: cover;
+        opacity: 0.7;
       }
 
-      .hero-subtitle {
-        font-size: 3rem;
-        opacity: 0.95;
-        line-height: 1;
+      &::after {
+        position: absolute;
+        background: rgba(0, 0, 0, 0.4);
+        content: '';
+        inset: 0;
       }
     }
+
+    .hero-content {
+      position: relative;
+      z-index: 1;
+    }
   }
 }
 ```
@@ -334,7 +366,7 @@ Import in `src/theme/_main.scss`:
 
 Now let's add VLT's powerful widgets to control block width and alignment. Update the schema file to add the schema enhancer.
 
-Update `src/components/blocks/myHero/schema.js`:
+Update `src/components/blocks/myHero/schema.ts`:
 
 ```javascript
 import { defineMessages } from 'react-intl';
diff --git a/docs/customizing-volto-light-theme/concepts.md b/docs/customizing-volto-light-theme/concepts.md
index f324158d9..a5d16434f 100644
--- a/docs/customizing-volto-light-theme/concepts.md
+++ b/docs/customizing-volto-light-theme/concepts.md
@@ -220,7 +220,7 @@ dependencies = [
     "plone.api",
     "plone.restapi",
     "plone.volto",
-    "kitconcept.voltolighttheme==7.3.0",
+    "kitconcept.voltolighttheme==7.3.1",
 ]
 ```
 

From a9f3ef7bfe3a9e029ba8680112bf7052b49d5220 Mon Sep 17 00:00:00 2001
From: iRohitSingh <isinghrohit0@gmail.com>
Date: Mon, 13 Oct 2025 09:51:11 +0300
Subject: [PATCH 04/10] minor fix

---
 docs/customizing-volto-light-theme/block-development-widgets.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/customizing-volto-light-theme/block-development-widgets.md b/docs/customizing-volto-light-theme/block-development-widgets.md
index 30b21f7c3..16209a8c4 100644
--- a/docs/customizing-volto-light-theme/block-development-widgets.md
+++ b/docs/customizing-volto-light-theme/block-development-widgets.md
@@ -285,7 +285,7 @@ Create `src/theme/blocks/_hero.scss`:
 .block.hero {
   position: relative;
   display: flex;
-  width: var(--default-container-width);
+  width: 100%;
   max-width: var(--block-width) !important;
   align-items: center;
   justify-content: center;

From b058e481caa5c8c3c9c8056753f197e67c55e8b3 Mon Sep 17 00:00:00 2001
From: iRohitSingh <isinghrohit0@gmail.com>
Date: Mon, 13 Oct 2025 22:18:24 +0300
Subject: [PATCH 05/10] fix the highlighting issue for sass and less and other
 build issue

---
 docs/conf.py                                                | 2 ++
 .../advanced-components-bm3.md                              | 4 +---
 .../block-development-widgets.md                            | 6 +-----
 docs/customizing-volto-light-theme/concepts.md              | 5 +----
 .../design-system-implementation.md                         | 4 +---
 docs/mastering-plone/events.md                              | 2 +-
 6 files changed, 7 insertions(+), 16 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index b97b86106..741c82bd6 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -6,6 +6,8 @@
 
 from datetime import datetime
 
+suppress_warnings = ["misc.highlighting_failure"]
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
diff --git a/docs/customizing-volto-light-theme/advanced-components-bm3.md b/docs/customizing-volto-light-theme/advanced-components-bm3.md
index 221f8f915..c463e6936 100644
--- a/docs/customizing-volto-light-theme/advanced-components-bm3.md
+++ b/docs/customizing-volto-light-theme/advanced-components-bm3.md
@@ -826,6 +826,4 @@ Vertical spacing between blocks is provided by the **upper block**:
 </div>
 ```
 
-Notice how the actual block content remains identical in both modes, while the framework containers handle all the differences in layout and editing functionality.
-
----
+Notice how the actual block content remains identical in both modes, while the framework containers handle all the differences in layout and editing functionality.
\ No newline at end of file
diff --git a/docs/customizing-volto-light-theme/block-development-widgets.md b/docs/customizing-volto-light-theme/block-development-widgets.md
index 16209a8c4..cc5016326 100644
--- a/docs/customizing-volto-light-theme/block-development-widgets.md
+++ b/docs/customizing-volto-light-theme/block-development-widgets.md
@@ -293,7 +293,6 @@ Create `src/theme/blocks/_hero.scss`:
   color: var(--theme-foreground-color);
   margin-inline: auto;
 
-  // default text view
   .hero-content {
     position: relative;
     z-index: 1;
@@ -323,7 +322,6 @@ Create `src/theme/blocks/_hero.scss`:
     }
   }
 
-  // has-image version
   &.has-image {
     color: #fff;
 
@@ -630,6 +628,4 @@ Import it in `_main.scss`:
 @import './blocks/hero';
 @import './blocks/relatedItems';
 @import './site';
-```
-
----
+```
\ No newline at end of file
diff --git a/docs/customizing-volto-light-theme/concepts.md b/docs/customizing-volto-light-theme/concepts.md
index a5d16434f..993331413 100644
--- a/docs/customizing-volto-light-theme/concepts.md
+++ b/docs/customizing-volto-light-theme/concepts.md
@@ -280,7 +280,4 @@ touch index.ts
 touch theme/_main.scss theme/_site.scss
 ```
 
-Remember that if you add new files to your project, it will be necessary to restart your Plone frontend.
-
-
----
\ No newline at end of file
+Remember that if you add new files to your project, it will be necessary to restart your Plone frontend.
\ No newline at end of file
diff --git a/docs/customizing-volto-light-theme/design-system-implementation.md b/docs/customizing-volto-light-theme/design-system-implementation.md
index eaadd9aa3..ff014bf02 100644
--- a/docs/customizing-volto-light-theme/design-system-implementation.md
+++ b/docs/customizing-volto-light-theme/design-system-implementation.md
@@ -260,6 +260,4 @@ In `src/theme/_main.scss`:
 
 ```scss
 @import './site';
-```
-
----
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/docs/mastering-plone/events.md b/docs/mastering-plone/events.md
index bcc7e0ddc..fd6b1b707 100644
--- a/docs/mastering-plone/events.md
+++ b/docs/mastering-plone/events.md
@@ -267,7 +267,7 @@ This trick does not yet work in Volto because some css-classes are still missing
 
 Modify {file}`frontend/theme/extras/custom.overrides` and add:
 
-```less
+```css
 /* Hide date fields from contributors */
 body.userrole-contributor {
   #default-start.field,

From 85a5da018ac8c9ac3f0175fd9162e819bdbf02a6 Mon Sep 17 00:00:00 2001
From: Tishasoumya-02 <tishasoumya@gmail.com>
Date: Sat, 29 Aug 2026 16:33:50 -0500
Subject: [PATCH 06/10] update installation guide

---
 .../customizing-volto-light-theme/concepts.md | 149 +++++++++++++-----
 1 file changed, 109 insertions(+), 40 deletions(-)

diff --git a/docs/customizing-volto-light-theme/concepts.md b/docs/customizing-volto-light-theme/concepts.md
index 993331413..1a3aa1049 100644
--- a/docs/customizing-volto-light-theme/concepts.md
+++ b/docs/customizing-volto-light-theme/concepts.md
@@ -6,6 +6,7 @@ myst:
     "property=og:title": "Foundation, Concepts & Project Setup"
     "keywords": "Plone, Volto, Training, Volto Light Theme"
 ---
+
 # Foundation, Concepts & Project Setup
 
 ## Volto Light Theme Core Concepts
@@ -15,6 +16,7 @@ Volto Light Theme (VLT) is a customizable theme built for the Volto frontend of
 ### Base Styling
 
 VLT is designed with simplicity and a minimal aesthetic in mind. The three core principles are:
+
 - **Consistency**: Predictable design patterns across all components
 - **Accessibility**: WCAG compliant with contrast checkers and semantic HTML
 - **Intuitiveness**: Clear visual hierarchy and user-friendly interfaces
@@ -22,6 +24,7 @@ VLT is designed with simplicity and a minimal aesthetic in mind. The three core
 ### Customizable Variables
 
 VLT offers a set of CSS custom properties (variables) that allow developers to customize various design elements:
+
 - **Colors**: Using paired foreground/background color system
 - **Spatial relationships**: Container widths and spacing scales
 - **Layouts**: Three-width container system
@@ -93,23 +96,23 @@ While the system can be extended with non-color CSS properties, the default four
 config.blocks.themes = [
   {
     style: {
-      '--theme-color': '#fff',
-      '--theme-high-contrast-color': '#ecebeb',
-      '--theme-foreground-color': '#000',
-      '--theme-low-contrast-foreground-color': '#555555',
+      "--theme-color": "#fff",
+      "--theme-high-contrast-color": "#ecebeb",
+      "--theme-foreground-color": "#000",
+      "--theme-low-contrast-foreground-color": "#555555",
     },
-    name: 'default',
-    label: 'Default',
+    name: "default",
+    label: "Default",
   },
   {
     style: {
-      '--theme-color': '#ecebeb',
-      '--theme-high-contrast-color': '#fff',
-      '--theme-foreground-color': '#000',
-      '--theme-low-contrast-foreground-color': '#555555',
+      "--theme-color": "#ecebeb",
+      "--theme-high-contrast-color": "#fff",
+      "--theme-foreground-color": "#000",
+      "--theme-low-contrast-foreground-color": "#555555",
     },
-    name: 'grey',
-    label: 'Grey',
+    name: "grey",
+    label: "Grey",
   },
 ];
 ```
@@ -122,9 +125,9 @@ VLT uses three types of container widths:
 
 ```scss
 // Three-width layout system
---layout-container-width: 1440px;  // for major elements like headers & large Blocks
---default-container-width: 940px;  // balanced content presentation for most Blocks
---narrow-container-width: 620px;   // optimal readability for text
+--layout-container-width: 1440px; // for major elements like headers & large Blocks
+--default-container-width: 940px; // balanced content presentation for most Blocks
+--narrow-container-width: 620px; // optimal readability for text
 ```
 
 The VLT `BlockWidthWidget` stores the value of the custom property `--block-width` so that it can be used by the StyleWrapper when injecting styles into the markup.
@@ -145,58 +148,115 @@ We recommend creating your Plone project with **Cookieplone**. Our comprehensive
 
 ## Installing Volto Light Theme
 
+VLT is shipped as two add-ons that you must install together:
+
+- the frontend Volto add-on `@kitconcept/volto-light-theme`, which is also a theme add-on,
+- the backend Plone add-on `kitconcept.voltolighttheme`, which provides the site customization behaviors.
+
+```{note}
+This training targets the VLT 8 line, which is currently released as alpha (`8.0.0-alpha.x` on npm, `8.0.0a.x` on PyPI), and is the version documented in the [official VLT install guide](https://volto-light-theme.readthedocs.io/how-to-guides/install.html).
+If you need a stable release instead, use the latest 7.x version of both packages and skip the "install the recommended add-ons as dependencies" step, since 7.x still ships them as `peerDependencies`.
+```
+
 ### Step 1: Install VLT and Recommended Block Add-ons
 
-Navigate to the `frontend/packages/my-vlt-project` folder and install VLT:
+VLT is installed like any other Volto add-on, as a dependency of your project add-on in {file}`frontend/packages/my-vlt-project/package.json`:
+
+```json
+{
+  "dependencies": {
+    "@kitconcept/volto-light-theme": "^8.0.0-alpha.31"
+  }
+}
+```
+
+From the root of your project, you can let pnpm add it to the workspace package for you:
 
 ```bash
-pnpm install @kitconcept/volto-light-theme@latest
+pnpm --filter my-vlt-project add @kitconcept/volto-light-theme@alpha
 ```
 
-Volto Light Theme comes with several pre-configured add-ons that provide basic blocks for your website. If you'd like to include them, you can add them in the `addons` section in your {file}`package.json`, but this is not required.
+Volto Light Theme supports all core blocks, and it also supports blocks coming from a set of recommended add-ons that provide the basic blocks for your website.
+Including them is not required, and you can pick only the ones you want to use.
 
-Here is the list of recommended addons to install, including VLT, which should be the last element:
+Since VLT 8.0.0, these recommended add-ons are no longer declared as `peerDependencies` of VLT, so you have to install them yourself as dependencies of your project add-on in {file}`frontend/packages/my-vlt-project/package.json`:
 
 ```json
-"addons": [
-  "@eeacms/volto-accordion-block",
-  "@kitconcept/volto-button-block",
-  "@kitconcept/volto-heading-block",
-  "@kitconcept/volto-highlight-block",
-  "@kitconcept/volto-introduction-block",
-  "@kitconcept/volto-separator-block",
-  "@kitconcept/volto-slider-block",
-  "@kitconcept/volto-light-theme"
-],
+{
+  "dependencies": {
+    "@eeacms/volto-accordion-block": "^12.0.0",
+    "@kitconcept/volto-banner-block": "^1.2.0",
+    "@kitconcept/volto-bm3-compat": "^1.0.0-alpha.1",
+    "@kitconcept/volto-button-block": "5.0.0-alpha.2",
+    "@kitconcept/volto-calendar-block": "^1.0.0-alpha.9",
+    "@kitconcept/volto-carousel-block": "^3.0.0-alpha.1",
+    "@kitconcept/volto-dsgvo-banner": "^4.0.0-alpha.2",
+    "@kitconcept/volto-heading-block": "^2.5.0",
+    "@kitconcept/volto-highlight-block": "^5.0.0-alpha.2",
+    "@kitconcept/volto-introduction-block": "^1.4.1",
+    "@kitconcept/volto-logos-block": "^4.0.0-alpha.1",
+    "@kitconcept/volto-separator-block": "^5.0.0-alpha.0",
+    "@kitconcept/volto-slider-block": "^7.0.0-alpha.1",
+    "@plonegovbr/volto-social-media": "^3.0.0-alpha.0",
+    "@kitconcept/volto-light-theme": "^8.0.0-alpha.31"
+  }
+}
+```
+
+```{note}
+The versions above are the known good versions at the time of writing.
+The source of truth, up-to-date list lives in the [recommended add-ons reference](https://volto-light-theme.readthedocs.io/reference/recommended-addons.html) of the VLT documentation.
 ```
 
-While in your project package folder, add VLT and the block addons to the `addons` list in your `package.json`:
+Installing a package is not enough: it also has to be declared as a Volto add-on in the `addons` key of the same {file}`package.json`, with VLT as the last element of the list:
 
 ```json
 {
-  "name": "my-vlt-project",
   "addons": [
     "@eeacms/volto-accordion-block",
+    "@kitconcept/volto-banner-block",
+    "@kitconcept/volto-bm3-compat",
     "@kitconcept/volto-button-block",
+    "@kitconcept/volto-carousel-block",
+    "@kitconcept/volto-dsgvo-banner",
     "@kitconcept/volto-heading-block",
     "@kitconcept/volto-highlight-block",
     "@kitconcept/volto-introduction-block",
+    "@kitconcept/volto-logos-block",
     "@kitconcept/volto-separator-block",
     "@kitconcept/volto-slider-block",
+    "@plonegovbr/volto-social-media",
     "@kitconcept/volto-light-theme"
   ]
 }
 ```
 
-**Important:** VLT must be the last addon in the list to ensure proper style cascade. Your project addon will still be the last applied if defined in `volto.config.js`.
+-**Important:** VLT must be the last addon in the list to ensure proper style cascade. Your project addon will still be the last applied if defined in `volto.config.js`.
+
+Run `pnpm install` from the project root after editing {file}`package.json` by hand, so that the workspace picks up the new dependencies.
 
 ### Step 2: Configure VLT as the Theme Provider
 
-Open the `volto.config.js` file in your `frontend` folder and modify it as shown below:
+VLT is not only a regular add-on, it is also a theme add-on, so it has to be declared as the theme of your project.
+How you do that depends on your Volto version.
+
+For Volto 18.29.1 or later, and 19.0.0-alpha.10 or later, declare it with the `theme` key of your project add-on {file}`frontend/packages/my-vlt-project/package.json`, next to the `addons` key:
+
+```json
+{
+  "addons": [
+    ...,
+    "@kitconcept/volto-light-theme"
+  ],
+  "theme": "@kitconcept/volto-light-theme"
+}
+```
+
+For older Volto versions, open the {file}`volto.config.js` file in your `frontend` folder and declare the theme there:
 
 ```javascript
-const addons = ['my-vlt-project'];
-const theme = '@kitconcept/volto-light-theme';
+const addons = ["my-vlt-project"];
+const theme = "@kitconcept/volto-light-theme";
 
 module.exports = {
   addons,
@@ -214,16 +274,22 @@ In your backend folder, install the Python package for site customization behavi
 
 Edit `backend/pyproject.toml` and add to the dependencies array:
 
-```
+```toml
 dependencies = [
-    "Products.CMFPlone==6.1.3",
+    "Products.CMFPlone==6.2.1",
     "plone.api",
     "plone.restapi",
     "plone.volto",
-    "kitconcept.voltolighttheme==7.3.1",
+    "kitconcept.voltolighttheme==8.0.0a31",
 ]
 ```
 
+Then install the dependency from your backend folder:
+
+```bash
+make install
+```
+
 ### Step 4: Install the Backend Add-on
 
 Start your development environment:
@@ -250,6 +316,9 @@ To enable site customization through the UI:
 2. In the "Behaviors" tab, activate the desired behaviors
 3. Click "Save"
 
+These behaviors let you customize the header, footer, and theme of your Plone site with knobs on the content type they are applied to, either the Plone site or a subsite.
+See the [site customization guide](https://volto-light-theme.readthedocs.io/conceptual-guides/site-customization.html) for the details of each behavior.
+
 Now your project should have the VLT Site configurations available.
 
 ## File Structure Setup
@@ -270,7 +339,7 @@ src/
     └── _site.scss
 ```
 
-Create the files:
+Create the files in `frontend/paackages/my-vlt-project` :
 
 ```bash
 cd src
@@ -280,4 +349,4 @@ touch index.ts
 touch theme/_main.scss theme/_site.scss
 ```
 
-Remember that if you add new files to your project, it will be necessary to restart your Plone frontend.
\ No newline at end of file
+Remember that if you add new files to your project, it will be necessary to restart your Plone frontend.

From 96f30ce06252df5f09aaa1fd382a2f5cdfe4dc38 Mon Sep 17 00:00:00 2001
From: Tishasoumya-02 <tishasoumya@gmail.com>
Date: Sat, 29 Aug 2026 16:58:48 -0500
Subject: [PATCH 07/10] update widgets and components docs

---
 .../block-development-widgets.md              | 347 +++++++++++++-----
 1 file changed, 251 insertions(+), 96 deletions(-)

diff --git a/docs/customizing-volto-light-theme/block-development-widgets.md b/docs/customizing-volto-light-theme/block-development-widgets.md
index cc5016326..6112760d8 100644
--- a/docs/customizing-volto-light-theme/block-development-widgets.md
+++ b/docs/customizing-volto-light-theme/block-development-widgets.md
@@ -37,6 +37,52 @@ Controls content alignment within blocks:
 }
 ```
 
+### ColorSwatch Widget
+
+Lets editors pick from a curated palette instead of entering free-form values.
+Each entry follows the `StyleDefinition` type from `@plone/types`, and you should always provide a `default` option so the field has a predictable fallback:
+
+```javascript
+{
+  widget: 'colorSwatch',
+  title: 'Background color',
+  default: 'default',
+  colors: [
+    {
+      name: 'default',
+      label: 'Default',
+      style: {
+        '--theme-color': '#fff',
+        '--theme-foreground-color': '#000',
+      },
+    },
+    {
+      name: 'grey',
+      label: 'Grey',
+      style: {
+        '--theme-color': '#ecebeb',
+        '--theme-foreground-color': '#000',
+      },
+    },
+  ],
+}
+```
+
+The widget stores the chosen color's `name` token, and the StyleWrapper adds that token as a CSS class on the block, so you can target it in your stylesheets.
+If you also want the CSS custom properties injected inline, register a `styleFieldDefinition` utility for the field name used in the schema:
+
+```javascript
+config.registerUtility({
+  name: "myColorField",
+  type: "styleFieldDefinition",
+  method: (props) => colors,
+});
+```
+
+```{note}
+This is the recommended way to use this widget, since it decouples the styles from the CSS and keeps a single source of truth for the color definitions.
+```
+
 ### ThemeColorSwatch Widget
 
 Allows selection from configured themes stored in `config.blocks.themes`:
@@ -61,6 +107,116 @@ Allows introducing a list of ordered objects with drag and drop:
 }
 ```
 
+### ColorPicker Widget
+
+A real color picker, with an RGB visual color chooser and a `hex` color field:
+
+```javascript
+{
+  widget: 'colorPicker',
+  title: 'Custom color',
+}
+```
+
+### color_picker Widget
+
+A Semantic UI-free drop-in replacement that overrides Volto's `color_picker` widget.
+Given an array of color definitions, it displays the colors that editors can choose:
+
+```javascript
+{
+  widget: 'color_picker',
+  title: 'Color',
+  colors: [
+    { name: 'default', label: 'Default' },
+    { name: 'grey', label: 'Grey' },
+  ],
+}
+```
+
+### Size Widget
+
+Selects the block size from a default list of values, one of either `small`, `medium`, or `large`:
+
+```javascript
+{
+  widget: 'size',
+  title: 'Size',
+  default: 'medium',
+}
+```
+
+Like the BlockAlignment widget, it is based on the Buttons component under the hood, so its actions and the styles they apply are configurable.
+
+### SoftText and SoftTextarea Widgets
+
+`softTextWidget` and `softTextareaWidget` behave like the `text` and `textarea` widgets, but they display a real-time character count while typing.
+When the count exceeds the limit set in `softMaxLength`, a notification appears, but the editor is still allowed to save the content.
+
+These widgets are configured from the backend, with `directives.widget` and its `frontendOptions`:
+
+```python
+directives.widget(
+    "seo_title",
+    frontendOptions={
+        "widget": "softTextWidget",
+        "widgetProps": {"softMaxLength": "55"},
+    },
+)
+seo_title = schema.TextLine(
+    title="SEO Title",
+    description="Override the meta title. Use maximum 55 characters.",
+    required=False,
+)
+```
+
+### ColorContrastChecker Component
+
+Not a widget itself, but a component that calculates the contrast ratio between two colors following the WCAG accessibility guidelines.
+Add it after a color input field in your own widget to warn the editor in real time about insufficient contrast:
+
+```jsx
+import ContrastChecker from "./ContrastChecker";
+
+const MyColorWidget = (props) => {
+  return (
+    <>
+      <FormFieldWrapper {...props} />
+      <ContrastChecker {...props} />
+    </>
+  );
+};
+
+export default MyColorWidget;
+```
+
+It accepts hex color codes, and compares the value of the field against its paired color.
+The pairings and their defaults are defined in `config.settings.colorMap`:
+
+```javascript
+config.settings.colorMap = {
+  primary_color: {
+    colorPair: "primary_foreground_color",
+    default: "#ffffff",
+  },
+  primary_foreground_color: {
+    colorPair: "primary_color",
+    default: "#000000",
+  },
+};
+```
+
+### Buttons Component
+
+Another helper rather than a widget, used to build widgets that show a list of buttons where a single value can be toggled.
+The BlockAlignment and Size widgets are built on top of it.
+You can pass it a configurable list of `actions`, along with the icon and the i18n message used for each one in `actionsInfoMap`, and filter out the default actions you don't want with `filterActions`.
+
+```{note}
+As of VLT 8.0.0-alpha.5 these components were moved to the Volto core package.
+If you are on Volto 19.0.0-alpha.12 or later, use the ones from Volto core instead of the ones provided by VLT.
+```
+
 ## Creating a Custom Hero Block
 
 Let's build a hero block step by step, starting with a basic implementation and then enhancing it with VLT widgets.
@@ -70,24 +226,24 @@ Let's build a hero block step by step, starting with a basic implementation and
 Create `src/components/blocks/myHero/schema.ts`:
 
 ```javascript
-import { defineMessages } from 'react-intl';
+import { defineMessages } from "react-intl";
 
 const messages = defineMessages({
   hero: {
-    id: 'Hero',
-    defaultMessage: 'Hero',
+    id: "Hero",
+    defaultMessage: "Hero",
   },
   title: {
-    id: 'Title',
-    defaultMessage: 'Title',
+    id: "Title",
+    defaultMessage: "Title",
   },
   subtitle: {
-    id: 'Subtitle',
-    defaultMessage: 'Subtitle',
+    id: "Subtitle",
+    defaultMessage: "Subtitle",
   },
   backgroundImage: {
-    id: 'Background Image',
-    defaultMessage: 'Background Image',
+    id: "Background Image",
+    defaultMessage: "Background Image",
   },
 });
 
@@ -98,29 +254,29 @@ const heroBlockSchema = (props) => {
     title: intl.formatMessage(messages.hero),
     fieldsets: [
       {
-        id: 'default',
-        title: 'Default',
-        fields: ['title', 'subtitle'],
+        id: "default",
+        title: "Default",
+        fields: ["title", "subtitle"],
       },
       {
-        id: 'design',
-        title: 'Design',
-        fields: ['backgroundImage'],
+        id: "design",
+        title: "Design",
+        fields: ["backgroundImage"],
       },
     ],
     properties: {
       title: {
         title: intl.formatMessage(messages.title),
-        type: 'string',
+        type: "string",
       },
       subtitle: {
         title: intl.formatMessage(messages.subtitle),
-        type: 'string',
+        type: "string",
       },
       backgroundImage: {
         title: intl.formatMessage(messages.backgroundImage),
-        widget: 'object_browser',
-        mode: 'image',
+        widget: "object_browser",
+        mode: "image",
         allowExternals: false,
       },
     },
@@ -136,28 +292,28 @@ export { heroBlockSchema };
 Create `src/components/blocks/myHero/View.tsx`:
 
 ```tsx
-import React from 'react';
-import cx from 'classnames';
-import config from '@plone/volto/registry';
-import { flattenToAppURL, isInternalURL } from '@plone/volto/helpers/Url/Url';
-import type { BlockViewProps } from '@plone/types';
+import React from "react";
+import cx from "classnames";
+import config from "@plone/volto/registry";
+import { flattenToAppURL, isInternalURL } from "@plone/volto/helpers/Url/Url";
+import type { BlockViewProps } from "@plone/types";
 
 const HeroView = (props: BlockViewProps) => {
   const { className, style } = props;
   const { title, subtitle, backgroundImage, url } = props?.data || {};
 
-  const hasImage = backgroundImage?.[0]?.['@id'];
+  const hasImage = backgroundImage?.[0]?.["@id"];
 
   let renderedImage = null;
   if (hasImage) {
-    const Image = config.getComponent('Image').component;
+    const Image = config.getComponent("Image").component;
     const imageItem = backgroundImage[0];
 
     if (Image) {
       renderedImage = (
         <Image
           item={{
-            '@id': imageItem['@id'],
+            "@id": imageItem["@id"],
             image_field: imageItem.image_field,
             image_scales: imageItem.image_scales,
           }}
@@ -170,9 +326,9 @@ const HeroView = (props: BlockViewProps) => {
       renderedImage = (
         <img
           src={
-            isInternalURL(url?.['@id'])
-              ? `${flattenToAppURL(url['@id'])}/@@images/image`
-              : url?.['@id']
+            isInternalURL(url?.["@id"])
+              ? `${flattenToAppURL(url["@id"])}/@@images/image`
+              : url?.["@id"]
           }
           alt=""
           loading="lazy"
@@ -183,7 +339,7 @@ const HeroView = (props: BlockViewProps) => {
 
   return (
     <div
-      className={cx('block hero', className, { 'has-image': hasImage })}
+      className={cx("block hero", className, { "has-image": hasImage })}
       style={style}
     >
       {hasImage && <div className="hero-image-wrapper">{renderedImage}</div>}
@@ -206,13 +362,13 @@ export default HeroView;
 Create `src/components/blocks/myHero/Edit.tsx`:
 
 ```tsx
-import React from 'react';
-import { useIntl } from 'react-intl';
-import SidebarPortal from '@plone/volto/components/manage/Sidebar/SidebarPortal';
-import { BlockDataForm } from '@plone/volto/components/manage/Form';
-import { heroBlockSchema } from './schema';
-import HeroView from './View';
-import type { BlockEditProps } from '@plone/types';
+import React from "react";
+import { useIntl } from "react-intl";
+import SidebarPortal from "@plone/volto/components/manage/Sidebar/SidebarPortal";
+import { BlockDataForm } from "@plone/volto/components/manage/Form";
+import { heroBlockSchema } from "./schema";
+import HeroView from "./View";
+import type { BlockEditProps } from "@plone/types";
 
 const HeroEdit = (props: BlockEditProps) => {
   const { selected, onChangeBlock, block, data } = props;
@@ -249,28 +405,28 @@ export default HeroEdit;
 Update `src/config/blocks.ts`:
 
 ```typescript
-import type { ConfigType } from '@plone/registry';
-import HeroView from '../components/blocks/myHero/View';
-import HeroEdit from '../components/blocks/myHero/Edit';
-import { heroBlockSchema } from '../components/blocks/myHero/schema';
-import heroSVG from '@plone/volto/icons/hero.svg';
+import type { ConfigType } from "@plone/registry";
+import HeroView from "../components/blocks/myHero/View";
+import HeroEdit from "../components/blocks/myHero/Edit";
+import { heroBlockSchema } from "../components/blocks/myHero/schema";
+import heroSVG from "@plone/volto/icons/hero.svg";
 
 export default function install(config: ConfigType) {
   // ... block themes configuration ...
 
   // Register Hero Block
   config.blocks.blocksConfig.hero = {
-    id: 'hero',
-    title: 'Hero',
+    id: "hero",
+    title: "Hero",
     icon: heroSVG,
-    group: 'common',
+    group: "common",
     view: HeroView,
     edit: HeroEdit,
     restricted: false,
     mostUsed: true,
     blockSchema: heroBlockSchema,
     sidebarTab: 1,
-    category: 'hero',
+    category: "hero",
   };
 
   return config;
@@ -340,7 +496,7 @@ Create `src/theme/blocks/_hero.scss`:
       &::after {
         position: absolute;
         background: rgba(0, 0, 0, 0.4);
-        content: '';
+        content: "";
         inset: 0;
       }
     }
@@ -356,8 +512,8 @@ Create `src/theme/blocks/_hero.scss`:
 Import in `src/theme/_main.scss`:
 
 ```scss
-@import './blocks/hero';
-@import './site';
+@import "./blocks/hero";
+@import "./site";
 ```
 
 ### Step 6: Enhance with VLT Widgets
@@ -367,32 +523,32 @@ Now let's add VLT's powerful widgets to control block width and alignment. Updat
 Update `src/components/blocks/myHero/schema.ts`:
 
 ```javascript
-import { defineMessages } from 'react-intl';
+import { defineMessages } from "react-intl";
 
 const messages = defineMessages({
   hero: {
-    id: 'Hero',
-    defaultMessage: 'Hero',
+    id: "Hero",
+    defaultMessage: "Hero",
   },
   title: {
-    id: 'Title',
-    defaultMessage: 'Title',
+    id: "Title",
+    defaultMessage: "Title",
   },
   subtitle: {
-    id: 'Subtitle',
-    defaultMessage: 'Subtitle',
+    id: "Subtitle",
+    defaultMessage: "Subtitle",
   },
   backgroundImage: {
-    id: 'Background Image',
-    defaultMessage: 'Background Image',
+    id: "Background Image",
+    defaultMessage: "Background Image",
   },
   blockWidth: {
-    id: 'Block Width',
-    defaultMessage: 'Block Width',
+    id: "Block Width",
+    defaultMessage: "Block Width",
   },
   textAlignment: {
-    id: 'Text Alignment',
-    defaultMessage: 'Text Alignment',
+    id: "Text Alignment",
+    defaultMessage: "Text Alignment",
   },
 });
 
@@ -403,29 +559,29 @@ const heroBlockSchema = (props) => {
     title: intl.formatMessage(messages.hero),
     fieldsets: [
       {
-        id: 'default',
-        title: 'Default',
-        fields: ['title', 'subtitle'],
+        id: "default",
+        title: "Default",
+        fields: ["title", "subtitle"],
       },
       {
-        id: 'design',
-        title: 'Design',
-        fields: ['backgroundImage'],
+        id: "design",
+        title: "Design",
+        fields: ["backgroundImage"],
       },
     ],
     properties: {
       title: {
         title: intl.formatMessage(messages.title),
-        type: 'string',
+        type: "string",
       },
       subtitle: {
         title: intl.formatMessage(messages.subtitle),
-        type: 'string',
+        type: "string",
       },
       backgroundImage: {
         title: intl.formatMessage(messages.backgroundImage),
-        widget: 'object_browser',
-        mode: 'image',
+        widget: "object_browser",
+        mode: "image",
         allowExternals: false,
       },
     },
@@ -437,21 +593,21 @@ const heroBlockSchema = (props) => {
 const heroSchemaEnhancer = ({ formData, schema, intl }) => {
   // Add custom fields to the styling schema at the beginning
   schema.properties.styles.schema.fieldsets[0].fields = [
-    'blockWidth:noprefix',
-    'align',
+    "blockWidth:noprefix",
+    "align",
     ...schema.properties.styles.schema.fieldsets[0].fields,
   ];
 
-  schema.properties.styles.schema.properties['blockWidth:noprefix'] = {
-    widget: 'blockWidth',
+  schema.properties.styles.schema.properties["blockWidth:noprefix"] = {
+    widget: "blockWidth",
     title: intl.formatMessage(messages.blockWidth),
-    default: 'default',
+    default: "default",
   };
 
   schema.properties.styles.schema.properties.align = {
-    widget: 'blockAlignment',
+    widget: "blockAlignment",
     title: intl.formatMessage(messages.textAlignment),
-    default: 'center',
+    default: "center",
   };
 
   return schema;
@@ -465,26 +621,26 @@ export { heroBlockSchema, heroSchemaEnhancer };
 Update `src/config/blocks.ts` to include the schema enhancer:
 
 ```typescript
-import type { ConfigType } from '@plone/registry';
-import HeroView from '../components/blocks/myHero/View';
-import HeroEdit from '../components/blocks/myHero/Edit';
+import type { ConfigType } from "@plone/registry";
+import HeroView from "../components/blocks/myHero/View";
+import HeroEdit from "../components/blocks/myHero/Edit";
 import {
   heroBlockSchema,
   heroSchemaEnhancer,
-} from '../components/blocks/myHero/schema';
-import { composeSchema } from '@plone/volto/helpers/Extensions';
-import { defaultStylingSchema } from '@kitconcept/volto-light-theme/components/Blocks/schema';
-import heroSVG from '@plone/volto/icons/hero.svg';
+} from "../components/blocks/myHero/schema";
+import { composeSchema } from "@plone/volto/helpers/Extensions";
+import { defaultStylingSchema } from "@kitconcept/volto-light-theme/components/Blocks/schema";
+import heroSVG from "@plone/volto/icons/hero.svg";
 
 export default function install(config: ConfigType) {
   // ... block themes configuration ...
 
   // Register Hero Block
   config.blocks.blocksConfig.hero = {
-    id: 'hero',
-    title: 'Hero',
+    id: "hero",
+    title: "Hero",
     icon: heroSVG,
-    group: 'common',
+    group: "common",
     view: HeroView,
     edit: HeroEdit,
     restricted: false,
@@ -492,7 +648,7 @@ export default function install(config: ConfigType) {
     blockSchema: heroBlockSchema,
     schemaEnhancer: composeSchema(defaultStylingSchema, heroSchemaEnhancer),
     sidebarTab: 1,
-    category: 'hero',
+    category: "hero",
   };
 
   return config;
@@ -619,13 +775,12 @@ Create `src/theme/blocks/_relatedItems.scss`:
     }
   }
 }
-
 ```
 
 Import it in `_main.scss`:
 
 ```scss
-@import './blocks/hero';
-@import './blocks/relatedItems';
-@import './site';
-```
\ No newline at end of file
+@import "./blocks/hero";
+@import "./blocks/relatedItems";
+@import "./site";
+```

From 42e0cc974fa7a6bad264a87cbdec3df1156db1af Mon Sep 17 00:00:00 2001
From: Tishasoumya-02 <tishasoumya@gmail.com>
Date: Sat, 29 Aug 2026 17:53:07 -0500
Subject: [PATCH 08/10] fix semantics

---
 .../block-development-widgets.md               | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/docs/customizing-volto-light-theme/block-development-widgets.md b/docs/customizing-volto-light-theme/block-development-widgets.md
index 6112760d8..2c845b76b 100644
--- a/docs/customizing-volto-light-theme/block-development-widgets.md
+++ b/docs/customizing-volto-light-theme/block-development-widgets.md
@@ -225,7 +225,7 @@ Let's build a hero block step by step, starting with a basic implementation and
 
 Create `src/components/blocks/myHero/schema.ts`:
 
-```javascript
+```typescript
 import { defineMessages } from "react-intl";
 
 const messages = defineMessages({
@@ -460,9 +460,9 @@ Create `src/theme/blocks/_hero.scss`:
     width: 100%;
     height: 100%;
     flex-direction: column;
-    align-items: var(--align--block-alignment);
+    align-items: var(--block-alignment);
     gap: 1rem;
-    text-align: var(--align--block-alignment);
+    text-align: var(--block-alignment);
 
     .hero-title {
       margin-bottom: $spacing-small;
@@ -522,7 +522,7 @@ Now let's add VLT's powerful widgets to control block width and alignment. Updat
 
 Update `src/components/blocks/myHero/schema.ts`:
 
-```javascript
+```typescript
 import { defineMessages } from "react-intl";
 
 const messages = defineMessages({
@@ -685,7 +685,7 @@ Update `src/theme/blocks/_hero.scss` to use the CSS custom properties set by the
       position: absolute;
       display: flex;
       flex-direction: column;
-      align-items: var(--align--block-alignment);
+      align-items: var(--block-alignment);
       width: 100%;
       height: 100%;
       padding: 4rem;
@@ -713,7 +713,7 @@ Let's learn how to integrate the `@plone-collective/volto-relateditems-block` in
 
 ### Install the Block
 
-To install the related items block, make sure you are in the `frontend/packages/volto-my-project` folder, and use the following command:
+To install the related items block, make sure you are in the `frontend/packages/my-vlt-project` folder, and use the following command:
 
 ```bash
 pnpm install @plone-collective/volto-relateditems-block@latest
@@ -724,12 +724,18 @@ Add it to your `package.json` addons (before VLT):
 ```json
 "addons": [
   "@eeacms/volto-accordion-block",
+  "@kitconcept/volto-banner-block",
+  "@kitconcept/volto-bm3-compat",
   "@kitconcept/volto-button-block",
+  "@kitconcept/volto-carousel-block",
+  "@kitconcept/volto-dsgvo-banner",
   "@kitconcept/volto-heading-block",
   "@kitconcept/volto-highlight-block",
   "@kitconcept/volto-introduction-block",
+  "@kitconcept/volto-logos-block",
   "@kitconcept/volto-separator-block",
   "@kitconcept/volto-slider-block",
+  "@plonegovbr/volto-social-media",
   "@plone-collective/volto-relateditems-block",
   "@kitconcept/volto-light-theme"
 ],

From 50e9df57751d87338101605d2828ebff26c55ffd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dante=20=C3=81lvarez?=
 <89805481+danalvrz@users.noreply.github.com>
Date: Tue, 15 Sep 2026 17:37:34 +0200
Subject: [PATCH 09/10] vlt 8 draft

---
 .../advanced-components-bm3.md                | 870 ++++++++++++------
 .../block-development-widgets.md              | 661 ++++++-------
 .../customizing-volto-light-theme/concepts.md | 371 +++++++-
 .../design-system-implementation.md           | 298 ++++--
 docs/customizing-volto-light-theme/index.md   |   2 +
 .../question-answer.md                        |  86 +-
 styles/config/vocabularies/Plone/accept.txt   |   1 +
 7 files changed, 1559 insertions(+), 730 deletions(-)

diff --git a/docs/customizing-volto-light-theme/advanced-components-bm3.md b/docs/customizing-volto-light-theme/advanced-components-bm3.md
index c463e6936..87ef67539 100644
--- a/docs/customizing-volto-light-theme/advanced-components-bm3.md
+++ b/docs/customizing-volto-light-theme/advanced-components-bm3.md
@@ -16,18 +16,33 @@ The Card primitive is VLT's reusable component for displaying content in card la
 ### Card Structure
 
 ```jsx
-<Card href="/path/to/item">
-  <Card.Image src="/path/to/image" />
+<Card item={robot}>
+  <Card.Image item={robot} />
   <Card.Summary>
-    <h2>Title</h2>
-    <p>Summary text goes here.</p>
+    <h2>ARM-7 Bench Arm</h2>
+    <p>Six-axis arm for precision bench work.</p>
   </Card.Summary>
   <Card.Actions>
-    <Button>Action 1</Button>
+    <Button>Book this unit</Button>
   </Card.Actions>
 </Card>
 ```
 
+### Making a Card Clickable
+
+A card becomes a link when you give it either an `item` or an `href`. The two are mutually exclusive, and `item` is the one to reach for when you have a content object:
+
+```jsx
+<Card item={robot}>...</Card>            // preferred: a Plone content object
+<Card href="/workshop/hours">...</Card>  // for arbitrary destinations
+```
+
+Passing `item` lets the underlying `UniversalLink` inspect the content type, so a File links to its download URL and an Image to its view, rather than to the object's default page.
+Passing `href={item['@id']}` skips that, and those types end up linking to the wrong place.
+Use `href` when you genuinely have only a URL.
+
+Pass `null` to make the card non-interactive, which is what listing templates do in edit mode.
+
 ### Card Variations
 
 - **Vertical layout** (default): Image on top
@@ -37,18 +52,18 @@ The Card primitive is VLT's reusable component for displaying content in card la
 
 ### Card.Image Slot
 
-Display an image using a `src` prop or use a Plone image object:
+Point the slot at a content object and it resolves the image from that item:
 
 ```tsx
-<Card.Image image={image} />
+<Card.Image item={robot} />
 ```
 
-Custom image component:
+A `src` prop works too, for an image that is not a content object. To control how the image is rendered, pass your own component:
 
 ```tsx
 <Card.Image
-  src="/path/to/image"
-  imageComponent={MyCustomImageComponent}
+  item={robot}
+  imageComponent={PreviewImageComponent}
 />
 ```
 
@@ -69,6 +84,10 @@ const Summary = config.getComponent({
 </Card.Summary>
 ```
 
+`Card` generates an id for the card's accessible name and builds a link component for the item, then passes both down to its slots as the `a11yLabelId` and `LinkToItem` props.
+Slots forward them to their children, so a Summary rendered inside `Card.Summary` receives them without you wiring anything up.
+Using them is what gives the card an accessible name and a real link—see the next section.
+
 ## Creating Custom Summary Components
 
 The Summary component displays content metadata in listings, teasers, and cards. VLT includes built-in implementations:
@@ -77,100 +96,191 @@ The Summary component displays content metadata in listings, teasers, and cards.
 - `NewsItemSummary`: Publication date, kicker, title, description
 - `EventSummary`: Start/end date, kicker, title, description
 - `FileSummary`: File size and type
+- `PersonSummary`: Contact details for the Person content type
+
+### The Summary Contract
+
+Every Summary receives the same props. Getting this shape right matters, because three of them are easy to miss:
+
+```ts
+type DefaultSummaryProps = {
+  item: Partial<ObjectBrowserItem>;   // the content object
+  LinkToItem?: React.ElementType;     // wraps the title in the card's link
+  HeadingTag?: React.ElementType;     // the heading level to render
+  a11yLabelId?: string;               // id that names the card
+  hide_description?: boolean;
+};
+```
+
+`item` is the content object. The other three are **siblings of `item`, not fields inside it**. A common mistake is to read them from `item`, where they will always be `undefined`.
+
+`DefaultSummary` shows the pattern to follow:
+
+```tsx
+const DefaultSummary = (props) => {
+  const {
+    item,
+    LinkToItem = React.Fragment,
+    HeadingTag = 'div',
+    a11yLabelId,
+  } = props;
+
+  return (
+    <>
+      {item?.head_title && <div className="headline">{item.head_title}</div>}
+      <HeadingTag className="title" id={a11yLabelId}>
+        <LinkToItem>{item.title ? item.title : item.id}</LinkToItem>
+      </HeadingTag>
+      {/* ... */}
+    </>
+  );
+};
+```
+
+The `id={a11yLabelId}` and the `<LinkToItem>` wrapper are not decoration.
+Together they give the card an accessible name and put a real link in the heading, which is how a keyboard or screen reader user reaches the item.
+A Summary that omits them renders a card that looks right but cannot be navigated.
 
-### Step 1: Create Product Content Type
+### Step 1: Create the Robot Content Type
 
-First, create a custom "Product" content type through the Plone UI:
+The Robotarium lends robots, so it needs a content type for them. Create it through the Plone UI:
 
 1. Go to http://localhost:3000/controlpanel/dexterity-types
 2. Click "Add New Content Type"
 3. Fill in:
-   - **Type Name**: Product
-   - **Short Name**: product (auto-filled)
-   - **Description**: A product with pricing information
+   - **Type Name**: Robot
+   - **Description**: A robot available for booking
 4. Click "Add"
 5. In the "Behaviors" tab, enable:
-   - "Kicker" (we'll use this field to store the price)
-   - "Preview image"
-   - Any other desired behaviors (Dublin Core, etc.)
+   - **Kicker field**, which adds `head_title`. We will use it to store the robot's charge level.
+   - **Preview Image**, so robots can show a photo in listings.
+   - Any other behaviors you want, such as Dublin Core metadata.
 6. Click "Save"
 
+```{note}
+The form asks only for a name and a description. Plone derives the type's id from the name by normalizing it, so **Robot** becomes `robot`, and a name like **Charging Station** would become `charging_station`.
+
+That id is what the REST API returns as the content's `@type`, and it is the value you register components against later in this chapter. It is worth confirming rather than assuming: open a robot you created and check the `@type` in `http://localhost:8080/Plone/<path>`, or look at the URL of the type you just added in the control panel.
+
+Plone's built-in types predate this rule and keep their historical ids, which is why VLT registers its news summary against `News Item`, with a space and capitals, rather than `news_item`.
+```
+
 ### Step 2: Create a Custom Summary Component
 
-Create `src/components/Summary/ProductSummary.tsx`:
+Create `src/components/Summary/RobotSummary.tsx`:
 
 ```tsx
+import * as React from 'react';
 import { FormattedNumber } from 'react-intl';
+import type { DefaultSummaryProps } from '@kitconcept/volto-light-theme/components/Summary/DefaultSummary';
 
-const ProductSummary = ({ item }) => {
+const RobotSummary = (props: DefaultSummaryProps) => {
   const {
-    title,
-    description,
-    HeadingTag = 'h3',
-    head_title,
-    currency = 'EUR',
-  } = item;
-  const price = parseFloat(head_title);
+    item,
+    LinkToItem = React.Fragment,
+    HeadingTag = 'div',
+    a11yLabelId,
+  } = props;
+  const { title, description, head_title } = item;
+  const charge = parseFloat(head_title);
 
   return (
     <>
-      <HeadingTag className="product-title">
-        {title ? title : item.id}
+      <HeadingTag className="title" id={a11yLabelId}>
+        <LinkToItem>{title ? title : item.id}</LinkToItem>
       </HeadingTag>
-      {description && <p className="product-description">{description}</p>}
-      {head_title && !isNaN(price) && (
-        <div className="product-price">
-          <span className="price">
-            <FormattedNumber
-              value={price}
-              style="currency"
-              currency={currency}
+      {description && <p className="description">{description}</p>}
+      {head_title && !isNaN(charge) && (
+        <div className="robot-charge">
+          <div className="charge-label">
+            <span>Charge</span>
+            <span className="charge">
+              <FormattedNumber value={charge / 100} style="percent" />
+            </span>
+          </div>
+          {/* The bar repeats the value the label already states, so it is
+              hidden from assistive technology rather than announced twice. */}
+          <div className="charge-track" aria-hidden="true">
+            <div
+              className="charge-level"
+              style={{ width: `${Math.min(Math.max(charge, 0), 100)}%` }}
             />
-          </span>
+          </div>
         </div>
       )}
     </>
   );
 };
 
-ProductSummary.hideLink = false;
-export default ProductSummary;
+RobotSummary.hideLink = false;
+export default RobotSummary;
 ```
 
-**Note**: We use the `head_title` field (kicker) to store price information. The price is formatted using `FormattedNumber` for proper currency display with EUR as default. In a real project, you would create custom fields for price and currency.
+The `HeadingTag` default is `'div'` rather than a fixed heading level. The caller decides the level, because the right one depends on where the listing sits in the page's heading outline.
+
+**Note**: We are reusing the kicker (`head_title`) to hold the charge level, so that the example needs no new field. A real Robotarium would add a proper numeric field to the Robot type instead, and reserve the kicker for what it is meant for: a line of text above the title.
+
+### Step 3: Add Styles for the Robot Summary
 
-### Step 3: Add Styles for Product Summary
+The charge is the one thing VLT has no styling for, so it is the one thing this partial has to describe: a labelled row above a slim track whose fill is as wide as the charge.
 
-Create `src/theme/_productSummary.scss`:
+Create `src/theme/_robotSummary.scss`:
 
 ```scss
-.products .card .card-summary {
-  padding-bottom: 0 !important;
-  .product-price {
-    font-size: 1.25rem;
-    color: var(--accent-color);
-    margin-top: 0.5rem;
-
-    .price {
-      background: var(--theme-high-contrast-color);
-      padding: 0.25rem 0.75rem;
-      border-radius: 4px;
-    }
+.robot-charge {
+  margin-top: $spacing-small;
+
+  .charge-label {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-bottom: 8px;
+    letter-spacing: 0.14em;
+    text-transform: uppercase;
+    @include headtitle2();
+  }
+
+  .charge-track {
+    overflow: hidden;
+    height: 5px;
+    border-radius: 999px;
+    background: color-mix(
+      in oklab,
+      var(--theme-foreground-color) 12%,
+      transparent
+    );
   }
 
-  .product-title {
-    margin-top: 0;
+  .charge-level {
+    height: 100%;
+    border-radius: 999px;
+    background: linear-gradient(
+      90deg,
+      color-mix(in oklab, var(--accent-color) 60%, #fff),
+      var(--accent-color)
+    );
   }
 }
+
+// Cards that carry a charge read as instrument panels, so give them an edge.
+.card:has(.robot-charge) {
+  border: 1px solid oklch(1 0 0 / 0.28);
+}
 ```
 
+Three decisions here are worth carrying to your own work.
+
+**Nothing is scoped to the listing.** A Summary is rendered in listings, in teasers, and in bare cards, and the same component should look the same in all of them. Scoping these rules to the fleet listing—`.robots .card .card-summary .robot-charge`—would style the listing and leave the same robot in a teaser looking like a different component. Selecting on what the Summary itself renders keeps the contexts in step.
+
 Import in `src/theme/_main.scss`:
 
 ```scss
-@import './blocks/hero';
-@import './blocks/relatedItems';
-@import './productSummary';
-@import './site';
+@import './blocks/button';
+@import './blocks/cover';
+@import './blocks/grid';
+@import './blocks/slider';
+@import './blocks/teaser';
+@import './robotSummary';
 ```
 
 ### Step 4: Register the Summary Component
@@ -178,79 +288,87 @@ Import in `src/theme/_main.scss`:
 In `src/config/settings.ts`:
 
 ```typescript
-import ProductSummary from '../components/Summary/ProductSummary';
+import RobotSummary from '../components/Summary/RobotSummary';
 
 export default function install(config: ConfigType) {
   // ... previous config ...
 
   config.registerComponent({
     name: 'Summary',
-    component: ProductSummary,
-    dependencies: ['product'],
+    component: RobotSummary,
+    dependencies: ['robot'],
   });
 
   return config;
 }
 ```
 
-### Step 5: Test the Product Summary
+### Step 5: Test the Robot Summary
 
-1. Create a Product item in your site
-2. Fill in the title, description, and kicker field (e.g., "$99.99")
-3. Add the Product to a Listing or Teaser block
-4. The custom ProductSummary will display the price, title, and description
+1. Add a Robot to your site, for example **ARM-7 Bench Arm**
+2. Fill in the title, a short description, and the kicker with a plain number such as `87`
+3. Add the robot to a Listing or Teaser block
+4. `RobotSummary` renders the title, description, and a charge level of 87%
 
 ## Creating Custom Listing Variations with Card Actions
 
-Listing variations customize content display in Listing blocks. Let's create a ProductTemplate demonstrating the Card.Actions slot for interactive buttons.
+Listing variations customize content display in Listing blocks. Let's build a `RobotsTemplate` that presents the fleet and uses the Card.Actions slot for a booking button.
 
 ### Card.Actions Slot
 
+```{important}
+`Card.Actions` only renders what a template puts in it, and **none of VLT's built-in listing variations put anything there**. Registering an `Actions` component is not enough on its own: List, List with images, Grid, and the Teaser block all ignore the slot, so a card rendered by any of them shows no actions.
+
+That is why the fleet listing below needs its own template. If you register an Actions component and see nothing, check which variation the listing is using before suspecting the registration.
+```
+
 The Card.Actions slot provides interactive elements beyond the main card link:
-- "Add to Cart" or "Get Now" buttons for products
-- "Download" buttons for files
-- "Register" buttons for events
+- "Book this unit" for a robot that is available
+- "Download spec sheet" for its documentation
+- "Reserve a slot" for a robot that is currently out
 
-### Step 1: Create ProductActions Component
+### Step 1: Create RobotActions Component
 
-Create `src/components/Actions/ProductActions.tsx`:
+Create `src/components/Actions/RobotActions.tsx`:
 
 ```tsx
-const ProductActions = ({ item }) => {
+const RobotActions = ({ item }) => {
   return (
-    <>
-      <button className="rent-now-button button">Rent now</button>
-    </>
+    <button type="button" className="book-unit-button button">
+      Book {item.title}
+    </button>
   );
 };
 
-export default ProductActions;
+export default RobotActions;
 ```
 
-### Step 2: Register ProductActions
+The button carries `type="button"` so it does not submit a surrounding form, and names the robot it belongs to. In a fleet listing, four buttons all reading "Book" are indistinguishable to someone moving through the page control by control; "Book ARM-7 Bench Arm" is not.
+
+### Step 2: Register RobotActions
 
 Update `src/config/settings.ts`:
 
 ```typescript
-import ProductActions from '../components/Actions/ProductActions';
+import RobotActions from '../components/Actions/RobotActions';
 
 export default function install(config: ConfigType) {
   // ... previous configuration ...
 
-  // Register ProductActions component
+  // Register RobotActions component
   config.registerComponent({
     name: 'Actions',
-    component: ProductActions,
-    dependencies: ['product'],
+    component: RobotActions,
+    dependencies: ['robot'],
   });
 
   return config;
 }
 ```
 
-### Step 3: Create ProductTemplate Listing Variation
+### Step 3: Create RobotsTemplate Listing Variation
 
-Create `src/components/blocks/Listing/ProductTemplate.tsx`:
+Create `src/components/blocks/Listing/RobotsTemplate.tsx`:
 
 ```tsx
 import React from 'react';
@@ -262,7 +380,7 @@ import config from '@plone/volto/registry';
 import DefaultSummary from '@kitconcept/volto-light-theme/components/Summary/DefaultSummary';
 import cx from 'classnames';
 
-const ProductTemplate = ({ items, linkTitle, linkHref, isEditMode }) => {
+const RobotsTemplate = ({ items, linkTitle, linkHref, isEditMode }) => {
   let link = null;
   let href = linkHref?.[0]?.['@id'] || '';
   const PreviewImageComponent = config.getComponent('PreviewImage').component;
@@ -279,7 +397,7 @@ const ProductTemplate = ({ items, linkTitle, linkHref, isEditMode }) => {
 
   return (
     <>
-      <div className="items">
+      <ul className="items">
         {items.map((item) => {
           const Summary =
             config.getComponent({
@@ -293,47 +411,52 @@ const ProductTemplate = ({ items, linkTitle, linkHref, isEditMode }) => {
           }).component;
 
           const showLink = !Summary.hideLink && !isEditMode;
+          const placeholderSrc =
+            config.settings.placeholderImages?.[item['@type']];
 
           return (
-            <div
+            <li
               className={cx('listing-item', {
                 [`${item['@type']?.toLowerCase()}-listing`]: item['@type'],
               })}
               key={item['@id']}
             >
-              <Card href={showLink ? item['@id'] : null}>
-                {item.image_field !== '' && (
+              <Card item={showLink ? item : null}>
+                {(item.image_field !== '' || placeholderSrc) && (
                   <Card.Image
                     className="item-image"
                     item={item}
+                    showPlaceholderImage={true}
+                    placeholderSrc={placeholderSrc}
                     imageComponent={PreviewImageComponent}
+                    sizes={`(max-width: ${config.settings.layout.tabletBreakpoint}px) 100vw, ${Math.trunc(config.settings.layout.defaultContainerWidth / 2)}px`}
                   />
                 )}
                 <Card.Summary>
-                  <Summary item={item} HeadingTag="h2" />
+                  <Summary item={item} />
                 </Card.Summary>
                 <Card.Actions>
                   {Actions && <Actions item={item} />}
                 </Card.Actions>
               </Card>
-            </div>
+            </li>
           );
         })}
-      </div>
+      </ul>
 
       {link && <div className="footer">{link}</div>}
     </>
   );
 };
 
-ProductTemplate.propTypes = {
+RobotsTemplate.propTypes = {
   items: PropTypes.arrayOf(PropTypes.any).isRequired,
   linkTitle: PropTypes.string,
   linkHref: PropTypes.any,
   isEditMode: PropTypes.bool,
 };
 
-export default ProductTemplate;
+export default RobotsTemplate;
 ```
 
 **Key Features:**
@@ -341,24 +464,35 @@ export default ProductTemplate;
 - `showLink` ensures cards are only clickable when appropriate
 - `isEditMode` disables navigation during editing
 - Dynamically renders Actions only for content types that have them registered
+- Renders a `<ul>` of `<li>` elements, matching VLT's own listing templates, so assistive technology announces the item count
+- Passes `item` to `Card` rather than a bare URL, so content types with their own link behavior, such as File, resolve correctly
+- Passes `sizes` and the placeholder props to `Card.Image`, exactly as VLT's own variations do
+
+```{important}
+Write a variation by starting from the VLT variation closest to what you want—here that is `GridTemplate`, since the fleet is a two-column card grid—and change only what has to change.
 
-### Step 4: Register ProductTemplate
+The two additions above are a good illustration of why. `sizes` tells the browser how wide the image will actually render, so that it downloads the right scale; omit it and the cards look soft for no visible reason. `showPlaceholderImage` and `placeholderSrc` keep the grid from collapsing on an item that has no image. Neither is obvious from the outside, and both come for free by following the shape of the template you are adapting.
+
+The same applies to the stylesheet in the next step.
+```
+
+### Step 4: Register RobotsTemplate
 
 Update `src/config/blocks.ts`:
 
 ```typescript
-import ProductTemplate from '../components/blocks/Listing/ProductTemplate';
+import RobotsTemplate from '../components/blocks/Listing/RobotsTemplate';
 
 export default function install(config: ConfigType) {
   // ... previous configuration ...
 
-  // Register ProductTemplate listing variation
+  // Register RobotsTemplate listing variation
   config.blocks.blocksConfig.listing.variations = [
     ...(config.blocks.blocksConfig.listing.variations || []),
     {
-      id: 'products',
-      title: 'Products',
-      template: ProductTemplate,
+      id: 'robots',
+      title: 'Robot Fleet',
+      template: RobotsTemplate,
     },
   ];
 
@@ -368,137 +502,158 @@ export default function install(config: ConfigType) {
 
 ### Step 5: Add Styles
 
+The fleet is a two-column card grid, which is what VLT's own `grid` variation already is—so the stylesheet is that variation's rules, repeated for `robots`, plus the two things the grid variation has no equivalent for: the card surface, and the actions row.
+
 Create `src/theme/blocks/_listing.scss`:
 
 ```scss
-.block.listing {
-  &.products {
-    max-width: var(--default-container-width) !important;
-    &.next--has--same--backgroundColor.next--is--same--block-type,
-    &.next--is--__button {
-      .listing-item:last-child {
-        padding-bottom: 0 !important;
-        border-bottom: none !important;
-      }
+// The Robot Fleet variation is a two-column card grid, which is exactly what
+// VLT's own `grid` variation already is. These rules mirror `.block.listing.grid`
+// in VLT's `theme/blocks/_listing.scss` and `theme/_layout.scss`; the only
+// additions are the card surface and the actions row, which the grid variation
+// has no equivalent for.
+
+// VLT constrains most listing variations per item, and the grid variation as a
+// whole. A card grid needs the second treatment, so repeat for `robots` what
+// VLT does for `& > .block.listing.grid`. View mode only — in edit mode
+// `.block-editor-listing .items` is already the constrained element, and adding
+// a second cap on the block is what makes the fleet listing sit off-center there.
+#page-document .blocks-group-wrapper > .block.listing.robots {
+  @include default-container-width();
+  @include adjustMarginsToContainer($default-container-width);
+}
+
+.block.listing.robots {
+  &.next--has--same--backgroundColor.next--is--same--block-type,
+  &.next--is--__button {
+    .listing-item:last-child {
+      padding-bottom: 0 !important;
+      border-bottom: none !important;
     }
+  }
 
-    .items {
-      display: flex;
-      flex-wrap: wrap;
-      @media only screen and (max-width: $largest-mobile-screen) {
-        flex-direction: column;
+  .items {
+    display: flex;
+    flex-wrap: wrap;
 
-        .listing-item {
-          padding-bottom: 20px !important;
-        }
+    @media only screen and (max-width: $largest-mobile-screen) {
+      flex-direction: column;
+
+      .listing-item {
+        padding-bottom: $spacing-small !important;
       }
     }
-    .headline {
-      @include block-title();
-      margin-right: 0 !important;
-      margin-left: 0 !important;
-    }
-    .listing-item {
-      align-items: normal;
-      border-bottom: none;
-      margin: 0 !important;
-
-      @media only screen and (min-width: $tablet-breakpoint) {
-        width: 50%;
-        padding-top: 10px;
-        padding-bottom: 10px !important;
-
-        &:nth-child(2n) {
-          padding-left: 10px !important;
-        }
+  }
 
-        &:nth-child(2n + 1) {
-          padding-right: 10px !important;
-        }
+  .listing-item {
+    // Cards in a row are as tall as the tallest of them, and the actions have
+    // to sit on the bottom edge of each. That needs an unbroken chain of
+    // stretching boxes from the row down to `.card-inner` — an `align-self` on
+    // the actions alone does nothing while these are all still block boxes.
+    display: flex;
+    align-items: normal;
+    border-bottom: none;
+    margin: 0 !important;
 
-        &:last-child,
-        &:nth-last-child(2):not(:nth-child(2n)) {
-          padding-bottom: 0 !important;
-        }
+    @media only screen and (min-width: $tablet-breakpoint) {
+      width: 50%;
+      padding-top: 10px;
+      padding-bottom: 10px !important;
 
-        &:first-child,
-        &:nth-child(2) {
-          padding-top: 0 !important;
-        }
+      &:nth-child(2n) {
+        padding-left: 10px !important;
       }
 
-      &:last-child:nth-child(2n + 1) {
-        @media only screen and (min-width: $largest-mobile-screen) {
-          margin-left: 0 !important;
-        }
+      &:nth-child(2n + 1) {
+        padding-right: 10px !important;
       }
 
-      .card {
+      &:last-child,
+      &:nth-last-child(2):not(:nth-child(2n)) {
+        padding-bottom: 0 !important;
+      }
+
+      &:first-child,
+      &:nth-child(2) {
+        padding-top: 0 !important;
+      }
+    }
+
+    &:last-child:nth-child(2n + 1) {
+      @media only screen and (min-width: $largest-mobile-screen) {
+        margin-left: 0 !important;
+      }
+    }
+
+    .card {
+      display: flex;
+      flex-direction: column;
+      flex-grow: 1;
+
+      // VLT gives the grid variation's cards the theme's secondary surface from
+      // `use-theme-colors()`; `.robots` is not `.grid`, so say it here.
+      background-color: var(--theme-high-contrast-color);
+
+      .card-inner {
+        display: flex;
+        flex-direction: column;
         flex-grow: 1;
-        .card-inner {
-          background: var(--theme-high-contrast-color);
-          .image-wrapper {
-            img {
-              width: 100%;
-              margin: 0;
-              aspect-ratio: var(--image-aspect-ratio, $aspect-ratio) !important;
-            }
-          }
-          .card-summary {
-            padding: 0 $spacing-large $spacing-large $spacing-large;
-            margin-top: $spacing-medium;
-
-            .headline {
-              padding: 0 !important;
-              margin-bottom: $spacing-small;
-              letter-spacing: 1px;
-              text-transform: uppercase;
-              @include headtitle1();
-              @include word-break();
-            }
-
-            h2 {
-              margin: 0 0 $spacing-small 0;
-              @include text-heading-h3();
-            }
-            p {
-              margin-bottom: 0;
-              @include body-text();
-            }
-            p:empty {
-              display: none;
-            }
-          }
+        padding-bottom: $spacing-medium !important;
+
+        .image-wrapper img {
+          margin: 0;
+        }
 
-          .product-price {
-            display: flex;
-            justify-content: end;
-            padding: $spacing-small;
+        .card-summary {
+          display: flex;
+          flex-direction: column;
+          flex-grow: 1;
+          padding: $spacing-medium $spacing-small 0 $spacing-small;
+
+          .title {
+            margin: 0 0 $spacing-small 0 !important;
+            @include text-heading-h3();
+          }
 
-            .price {
-              font-size: 2.5rem;
-              width: 30%;
-            }
+          // As in the reference design: the charge bar sits on the bottom edge
+          // of the summary, so the bars line up across a row however long the
+          // descriptions are.
+          .robot-charge {
+            padding-top: $spacing-small;
+            margin-top: auto;
           }
         }
+      }
 
-        .actions-wrapper {
-          display: flex;
-          justify-content: end;
-          padding: 0 $spacing-large $spacing-medium $spacing-large;
-          .rent-now-button {
-            width: 30%;
-            padding: 0.75rem 1rem;
-            margin: 1rem;
-            background-color: var(--accent-color);
-            color: white;
-            border: none;
-            cursor: pointer;
-            transition: opacity 0.2s;
-
-            &:hover {
-              opacity: 0.9;
-            }
+      // The fleet's own addition: the Card.Actions slot, which none of VLT's
+      // variations fill.
+      .actions-wrapper {
+        // The last of the stretching boxes: `auto` here is what pins the
+        // actions to the bottom of a card that is taller than its content.
+        margin-top: auto;
+        padding: $spacing-small $spacing-small 0 $spacing-small;
+        text-align: right;
+
+        .book-unit-button {
+          padding: 8px 20px;
+          border: 1px solid var(--accent-color);
+          background: var(--accent-color);
+          color: var(--accent-foreground-color);
+          cursor: pointer;
+          transition:
+            background 0.2s ease,
+            color 0.2s ease,
+            border-color 0.2s ease;
+          @include body-text-bold();
+
+          // The inverse of the filled state, matching how the Button block
+          // inverts on hover. Both values are read from the theme's foreground,
+          // which is always a color — `--theme-color` may be a gradient.
+          &:hover,
+          &:focus {
+            border-color: var(--theme-foreground-color);
+            background: none;
+            color: var(--theme-foreground-color);
           }
         }
       }
@@ -510,72 +665,98 @@ Create `src/theme/blocks/_listing.scss`:
 Import in `src/theme/_main.scss`:
 
 ```scss
-@import './blocks/hero';
-@import './blocks/relatedItems';
+@import './blocks/button';
+@import './blocks/cover';
+@import './blocks/grid';
 @import './blocks/listing';
-@import './productSummary';
-@import './site';
+@import './blocks/slider';
+@import './blocks/teaser';
+@import './robotSummary';
 ```
 
-### Step 6: Test the Product Listing
+### Step 6: Test the Fleet Listing
 
-1. Create Product items with title, description, kicker (price), and images
+1. Add a few robots, such as **ARM-7 Bench Arm**, **ROVER-2 Terrain Scout**, **QUAD-4 Walker**, and **DRONE-1 Surveyor**, each with a description, a charge level in the kicker, and an image
 2. Add a Listing block to a page
-3. Select "Products" variation in block settings
-4. Configure to show Product content type
-5. Products display with image, summary, and "Get now" button
+3. Select the **Robot Fleet** variation in the block settings
+4. Configure the block to list the Robot content type
+5. Each robot appears with its image, summary, charge level, and a Book button
 
 ## Working with Slots
 
-VLT provides slots for extending the layout without component shadowing. Let's create a practical example: a newsletter signup component in the preFooter slot.
+VLT provides slots for extending the layout without component shadowing. Let's create a practical example: a sign-up form for **Signal**, the Robotarium's workshop bulletin, in the preFooter slot.
 
 ### Available Slots
 
-- `aboveHeader`: Content above header
-- `belowHeader`: Content below header
-- `headerTools`: Header tools at top-right (includes Anontools by default)
-- `preFooter`: Before footer
-- `postFooter`: After footer
-- `footer`: Main footer area
-- `footerLinks`: Footer links section
-- `followUs`: Social media section
+Volto core renders three slots, and VLT's header, footer, and listing add the rest:
+
+| Slot | Where | Arrives with |
+| --- | --- | --- |
+| `aboveApp` | Outermost, around the whole app | `plone-components-css` |
+| `aboveContent` | Above the content view | — |
+| `belowContent` | Below the content view | **`tags` and `relatedItems`** |
+| `aboveHeader` | Above the header | — |
+| `belowHeader` | Below the header | — |
+| `headerTools` | Header, top right | Anontools |
+| `preFooter` | Before the footer | — |
+| `footer` | Main footer area | VLT's footer |
+| `postFooter` | After the footer | — |
+| `footerLinks` | Footer links section | VLT's footer links |
+| `followUs` | Social media section | — |
+| `aboveListingItems` | Inside a Listing block, above the items | — |
+
+```{important}
+Most slots start empty, but `belowContent` does not.
+Volto registers `tags` and `relatedItems` into it by default, so every content view already renders a tag list and a related-items list before you add anything.
+
+Because the last registration wins, and add-on configuration runs after core's, you displace a built-in by re-registering its name with a component that renders nothing:
+
+    config.registerSlotComponent({
+      slot: 'belowContent',
+      name: 'relatedItems',
+      component: () => null,
+    });
+
+Check what a slot already contains before you register into it.
+```
 
-### Step 1: Create Newsletter Signup Component
+### Step 1: Create the Signal Sign-up Component
 
-Create `src/components/NewsletterSignup/NewsletterSignup.tsx`:
+Create `src/components/SignalSignup/SignalSignup.tsx`:
 
 ```tsx
 import React, { useState } from 'react';
 
-const NewsletterSignup = () => {
+const SignalSignup = () => {
   const [email, setEmail] = useState('');
 
   const handleSubmit = (e) => {
     e.preventDefault();
-    // In a real implementation, this would submit to a newsletter service
-    console.log('Newsletter signup:', email);
-    alert(`Thanks for signing up with ${email}!`);
+    // In a real implementation, this would submit to a mailing service
+    console.log('Signal sign-up:', email);
+    alert(`Thanks, ${email}. You are on the Signal list.`);
     setEmail('');
   };
 
   return (
-    <div className="newsletter-signup">
-      <div className="newsletter-container">
-        <h2 className="newsletter-title">Stay Updated</h2>
-        <p className="newsletter-description">
-          Subscribe to our newsletter for the latest updates and news.
+    <div className="signal-signup">
+      <div className="signal-container">
+        <h2 className="signal-title">Signal</h2>
+        <p className="signal-description">
+          Workshop notes, new arrivals, and downtime warnings. One message a month.
         </p>
-        <form onSubmit={handleSubmit} className="newsletter-form">
+        <form onSubmit={handleSubmit} className="signal-form">
           <input
             type="email"
             value={email}
             onChange={(e) => setEmail(e.target.value)}
-            placeholder="Enter your email"
+            aria-label="Email address"
+            placeholder="you@example.com"
             required
-            className="newsletter-input"
+            className="signal-input"
           />
-          <button type="submit" className="newsletter-button">
-            Subscribe
+          <button type="submit" className="signal-button">
+            Sign up
           </button>
         </form>
       </div>
@@ -583,37 +764,44 @@ const NewsletterSignup = () => {
   );
 };
 
-export default NewsletterSignup;
+export default SignalSignup;
 ```
 
 ### Step 2: Add Styles
 
-Create `src/theme/_newsletterSignup.scss`:
+Create `src/theme/_signalSignup.scss`:
 
 ```scss
-.newsletter-signup {
+// VLT pads the footer's first child with `#footer > :first-child:not(:empty)`
+// (1,1,0). The sign-up band brings its own padding and its own background, so
+// that padding shows up as a gap in the footer's gradient above it.
+#footer > .pre-footer:has(.signal-signup) {
+  padding: 0;
+}
+
+.signal-signup {
   background-color: var(--secondary-color);
   color: var(--secondary-foreground-color);
   padding: 4rem 2rem;
 
-  .newsletter-container {
+  .signal-container {
     max-width: var(--default-container-width);
     margin: 0 auto;
     text-align: center;
   }
 
-  .newsletter-title {
+  .signal-title {
     font-size: 2rem;
     margin-bottom: 1rem;
   }
 
-  .newsletter-description {
+  .signal-description {
     font-size: 1.125rem;
     margin-bottom: 2rem;
     opacity: 0.9;
   }
 
-  .newsletter-form {
+  .signal-form {
     display: flex;
     gap: 1rem;
     max-width: 500px;
@@ -621,7 +809,7 @@ Create `src/theme/_newsletterSignup.scss`:
     flex-wrap: wrap;
     justify-content: center;
 
-    .newsletter-input {
+    .signal-input {
       flex: 1;
       min-width: 250px;
       padding: 0.75rem 1rem;
@@ -636,7 +824,7 @@ Create `src/theme/_newsletterSignup.scss`:
       }
     }
 
-    .newsletter-button {
+    .signal-button {
       padding: 0.75rem 2rem;
       background-color: var(--accent-color);
       color: var(--accent-foreground-color);
@@ -661,12 +849,14 @@ Create `src/theme/_newsletterSignup.scss`:
 Import in `src/theme/_main.scss`:
 
 ```scss
-@import './blocks/hero';
-@import './blocks/relatedItems';
+@import './blocks/button';
+@import './blocks/cover';
+@import './blocks/grid';
 @import './blocks/listing';
-@import './productSummary';
-@import './site';
-@import './newsletterSignup';
+@import './blocks/slider';
+@import './blocks/teaser';
+@import './robotSummary';
+@import './signalSignup';
 ```
 
 ### Step 3: Register the Component to the Slot
@@ -674,22 +864,93 @@ Import in `src/theme/_main.scss`:
 In `src/config/settings.ts`:
 
 ```typescript
-import NewsletterSignup from '../components/NewsletterSignup/NewsletterSignup';
+import SignalSignup from '../components/SignalSignup/SignalSignup';
 
 export default function install(config: ConfigType) {
   // ... previous config ...
 
   config.registerSlotComponent({
-    name: 'NewsletterSignup',
+    name: 'SignalSignup',
     slot: 'preFooter',
-    component: NewsletterSignup,
+    component: SignalSignup,
   });
 
   return config;
 }
 ```
 
-The newsletter signup component will now appear before the footer on all pages, demonstrating how slots enable you to extend the layout without shadowing core components.
+The Signal sign-up now appears before the footer on every page, demonstrating how slots let you extend the layout without shadowing core components.
+
+## Swapping Structural Components
+
+Slots let you *add* to the layout. Sooner or later you will want to *replace* part of it—a navigation that your design calls for, a footer that VLT's does not cover.
+
+The old answer was to shadow the component by dropping a file into {file}`customizations`. VLT 8 offers a better one: its structural components are resolved through the registry at render time, so a project can substitute its own by registering it and naming it in configuration.
+
+### How It Works
+
+VLT registers each of its structural components as a utility under the name `vlt`, with a `type` naming the role:
+
+```typescript
+config.registerUtility({ name: 'vlt', type: 'navigation', method: Navigation });
+```
+
+A setting then decides which registered name renders for each role:
+
+```typescript
+config.settings.vlt = {
+  components: {
+    breadcrumbs: 'vlt',
+    footer: 'vlt',
+    header: 'vlt',
+    languageSelector: 'vlt',
+    logo: 'vlt',
+    mobileNavigation: 'vlt',
+    navigation: 'vlt',
+    searchWidget: 'vlt',
+    tags: 'vlt',
+  },
+};
+```
+
+These are the defaults, so out of the box nothing changes. The nine roles above are the ones you can swap.
+
+### Making the Swap
+
+Swapping a role takes two steps, and the Robotarium does not need either of them yet—the mechanism is worth knowing before you reach for it.
+
+First, register your implementation under a name of your own, against the role's `type`, in {file}`src/config/settings.ts`:
+
+```typescript
+config.registerUtility({
+  name: 'robotarium',
+  type: 'navigation',
+  method: MyNavigation,
+});
+```
+
+Both implementations now sit in the registry, and nothing renders differently yet. The second step selects yours:
+
+```typescript
+config.settings.vlt.components.navigation = 'robotarium';
+```
+
+That is the whole change. VLT's header resolves the navigation through the registry when it renders, so it picks up your component. Every other role keeps its `vlt` default, and VLT's own navigation stays registered under `vlt`—so reverting is a one-line edit, not a file deletion.
+
+The same two steps swap any of the nine roles.
+
+### Why Prefer This Over Shadowing
+
+- **Explicit.** The active component is named in configuration, not implied by a file's path.
+- **Composable.** Several implementations can coexist under different names, and you choose which one renders.
+- **Decoupled.** You bind to a role name, not to an internal module path that can move between VLT releases.
+- **Safe.** If a setting names a component that was never registered, VLT falls back to its own implementation rather than rendering nothing.
+- **Typed.** The keys of `config.settings.vlt.components` are a fixed set, so a misspelled role is a compile error rather than a silent no-op.
+
+```{note}
+Your add-on must be applied after `@kitconcept/volto-light-theme` so that `config.settings.vlt` exists when you assign to it.
+Keeping VLT last in your project add-on's `addons` list, as set up in the first chapter, is enough.
+```
 
 ## Site Customization Behaviors
 
@@ -702,6 +963,7 @@ Through the Plone UI, you can customize:
 - **Complementary logo**: Second logo on the right side
 - **Fat menu**: Enabled by default, can be disabled
 - **Intranet header**: Alternative header for intranet sites
+- **Site flag**: The colored pill at the top left of the header
 - **Actions**: Links at the top right
 
 ### Theme Customization Options
@@ -733,6 +995,8 @@ Block Model v3 introduces a unified container architecture that ensures consiste
 - Improved spacing control through block categories
 - Reduced maintenance overhead
 
+(bm3-two-container-label)=
+
 ### The Two-Container System
 
 Every block in Block Model v3 follows this structure:
@@ -757,7 +1021,7 @@ Every block in Block Model v3 follows this structure:
 ```
 
 **Main/Outer Container:**
-- Full width (extends edge to edge)
+- Spans the full layout width
 - Handles background colors and theme variables
 - Uses padding (not margin) for vertical spacing
 - CSS Classes: `.block.${type}.category-${category}`
@@ -770,27 +1034,59 @@ Every block in Block Model v3 follows this structure:
 
 ### Enable Block Model v3
 
+VLT ships with `config.settings.blockModel = 2` and copies that value onto each block it has migrated. Opting in means setting the flag and re-applying it to those blocks, because they read the value at the time VLT was configured—which is before your add-on runs.
+
 In your project's `src/config/settings.ts`:
 
 ```typescript
 export default function install(config: ConfigType) {
-  // Enable Block Model v3
+  // ... previous configuration ...
+
+  // Enable Block Model v3 globally
   config.settings.blockModel = 3;
-  config.blocks.blocksConfig.slate.blockModel = config.settings.blockModel;
-  config.blocks.blocksConfig.title.blockModel = config.settings.blockModel;
-  config.blocks.blocksConfig.__button.blockModel = config.settings.blockModel;
-  // Define block categories for spacing
-  config.blocks.blocksConfig.slate.category = 'inline';
-  config.blocks.blocksConfig.title.category = 'title';
-  config.blocks.blocksConfig.__button.category = 'action';
+
+  // Re-apply it to the blocks VLT has migrated
+  for (const type of ['slate', 'title', '__button']) {
+    config.blocks.blocksConfig[type].blockModel = config.settings.blockModel;
+  }
 
   return config;
 }
 ```
 
+```{important}
+Check each block's repository for the "BMv3 ready" banner before you flip it.
+```
+
 ### Block Categories
 
-Block categories determine spacing relationships between adjacent blocks. Categories are available at `config.blocks.blocksConfig.[$type].category`.
+Block categories determine spacing relationships between adjacent blocks, through the `category-${category}` class on the outer container. They are set at `config.blocks.blocksConfig.[$type].category`.
+
+VLT already assigns categories to the blocks it has migrated, so you do not need to repeat them:
+
+| Category | Blocks | Spacing behavior |
+| --- | --- | --- |
+| `inline` | `slate` | Flows as body text |
+| `title` | `title` | Opens a section |
+| `action` | `__button` | A call to action |
+| `cards` | `gridBlock` | Self-contained visual units |
+
+Your own blocks need a category too, and the useful instinct is to reach for one of these four before inventing a fifth. The Cover block renders a self-contained visual unit with its own background, which is what `cards` already describes, so it can reuse it.
+
+These two lines go in {file}`src/config/blocks.ts`, **after** the Cover registration from the previous chapter. They are worth adding even with the flag left at `2`—`blockModel` simply picks up whatever `config.settings.blockModel` currently holds:
+
+```typescript
+config.blocks.blocksConfig.cover.category = 'cards';
+config.blocks.blocksConfig.cover.blockModel = config.settings.blockModel;
+```
+
+```{warning}
+The file matters here, and so does the position within it.
+
+{file}`src/index.ts` calls `installSettings` before `installBlocks`, so at the time {file}`config/settings.ts` runs, `config.blocks.blocksConfig.cover` does not exist yet—putting these lines there alongside `config.settings.blockModel = 3` throws. They have to run after the block is registered, and after the flag is set, which {file}`config/blocks.ts` satisfies on both counts.
+```
+
+Add a category of your own only when a block genuinely spaces differently from all four. When you do, name it for the family it opens rather than for the block that prompted it, and remember that a category only means something if your stylesheets act on the `category-*` class it produces.
 
 Vertical spacing between blocks is provided by the **upper block**:
 - Block content should be flush with top of container
@@ -826,4 +1122,26 @@ Vertical spacing between blocks is provided by the **upper block**:
 </div>
 ```
 
-Notice how the actual block content remains identical in both modes, while the framework containers handle all the differences in layout and editing functionality.
\ No newline at end of file
+Notice how the actual block content remains identical in both modes, while the framework containers handle all the differences in layout and editing functionality.
+### The `volto-bm3-compat` add-on
+
+Block Model v3 changes the markup a block renders into, so blocks written against the older model need their styles adapting. `@kitconcept/volto-bm3-compat` bridges that gap, and VLT declares it as an add-on of its own, so it is already in your dependency tree if you followed the install chapter.
+
+Check the block's repository for the "BMv3 ready" banner before enabling the new model on a block you did not write.
+
+## Checkpoint
+
+- `config.settings.vlt.components` lists the nine swappable roles, each still set to `vlt`. Naming a component that was never registered under one of them falls back to VLT's own rather than rendering nothing.
+- The Signal sign-up form appears above the footer on every page.
+- A Listing block set to the **Robot Fleet** variation shows each charge level as a labelled bar, the Book buttons line up along the bottom of the cards whatever the description lengths, and tabbing through the page reaches every robot title as a link.
+- The same robot in a Teaser block renders the same title, description, and charge bar as it does in the fleet listing.
+- If—and only if—you enabled Block Model v3, a Slate block renders inside a `.block-inner-container` and looks the same in edit mode as in view mode. With the flag left at `2`, as the Robotarium leaves it, every block still renders through the v2 path.
+
+## Further Reading
+
+- [Swap structural components](https://volto-light-theme.readthedocs.io/how-to-guides/swap-structural-components.html)
+- [Slots reference](https://volto-light-theme.readthedocs.io/reference/slots.html)
+- [Card primitive reference](https://volto-light-theme.readthedocs.io/reference/card.html)
+- [Summary components](https://volto-light-theme.readthedocs.io/how-to-guides/summary.html)
+- [Site customization](https://volto-light-theme.readthedocs.io/conceptual-guides/site-customization.html)
+- [Block Model v3](https://volto-light-theme.readthedocs.io/conceptual-guides/block-model-v3.html)
diff --git a/docs/customizing-volto-light-theme/block-development-widgets.md b/docs/customizing-volto-light-theme/block-development-widgets.md
index 2c845b76b..565e2ec60 100644
--- a/docs/customizing-volto-light-theme/block-development-widgets.md
+++ b/docs/customizing-volto-light-theme/block-development-widgets.md
@@ -73,8 +73,8 @@ If you also want the CSS custom properties injected inline, register a `styleFie
 
 ```javascript
 config.registerUtility({
-  name: "myColorField",
-  type: "styleFieldDefinition",
+  name: 'myColorField',
+  type: 'styleFieldDefinition',
   method: (props) => colors,
 });
 ```
@@ -83,18 +83,6 @@ config.registerUtility({
 This is the recommended way to use this widget, since it decouples the styles from the CSS and keeps a single source of truth for the color definitions.
 ```
 
-### ThemeColorSwatch Widget
-
-Allows selection from configured themes stored in `config.blocks.themes`:
-
-```javascript
-{
-  widget: 'themeColorSwatch',
-  title: 'Color Theme',
-  colors: config.blocks.themes,
-}
-```
-
 ### ObjectList Widget
 
 Allows introducing a list of ordered objects with drag and drop:
@@ -136,16 +124,27 @@ Given an array of color definitions, it displays the colors that editors can cho
 
 ### Size Widget
 
-Selects the block size from a default list of values, one of either `small`, `medium`, or `large`:
+Selects the block size from a default list of three values.
+The stored values are the tokens `s`, `m`, and `l`. The names Small, Medium, and Large are only their labels, so a `default` must be one of the tokens:
 
 ```javascript
 {
   widget: 'size',
   title: 'Size',
-  default: 'medium',
+  default: 'm',
 }
 ```
 
+VLT maps each token to the `--media-size` custom property through `config.blocks.sizes`, resolved by the `size:noprefix` style field:
+
+```typescript
+config.blocks.sizes = [
+  { style: { '--media-size': 'var(--size-small)' }, name: 's', label: 'Small' },
+  { style: { '--media-size': 'var(--size-medium)' }, name: 'm', label: 'Medium' },
+  { style: { '--media-size': 'var(--size-large)' }, name: 'l', label: 'Large' },
+];
+```
+
 Like the BlockAlignment widget, it is based on the Buttons component under the hood, so its actions and the styles they apply are configurable.
 
 ### SoftText and SoftTextarea Widgets
@@ -173,10 +172,11 @@ seo_title = schema.TextLine(
 ### ColorContrastChecker Component
 
 Not a widget itself, but a component that calculates the contrast ratio between two colors following the WCAG accessibility guidelines.
+It is provided by VLT, at `@kitconcept/volto-light-theme/components/Widgets/ColorContrastChecker`.
 Add it after a color input field in your own widget to warn the editor in real time about insufficient contrast:
 
 ```jsx
-import ContrastChecker from "./ContrastChecker";
+import ContrastChecker from '@kitconcept/volto-light-theme/components/Widgets/ColorContrastChecker';
 
 const MyColorWidget = (props) => {
   return (
@@ -196,12 +196,12 @@ The pairings and their defaults are defined in `config.settings.colorMap`:
 ```javascript
 config.settings.colorMap = {
   primary_color: {
-    colorPair: "primary_foreground_color",
-    default: "#ffffff",
+    colorPair: 'primary_foreground_color',
+    default: '#ffffff',
   },
   primary_foreground_color: {
-    colorPair: "primary_color",
-    default: "#000000",
+    colorPair: 'primary_color',
+    default: '#000000',
   },
 };
 ```
@@ -213,70 +213,74 @@ The BlockAlignment and Size widgets are built on top of it.
 You can pass it a configurable list of `actions`, along with the icon and the i18n message used for each one in `actionsInfoMap`, and filter out the default actions you don't want with `filterActions`.
 
 ```{note}
-As of VLT 8.0.0-alpha.5 these components were moved to the Volto core package.
-If you are on Volto 19.0.0-alpha.12 or later, use the ones from Volto core instead of the ones provided by VLT.
+As of VLT 8.0.0-alpha.5, four of these components live in Volto core rather than in VLT: `ButtonsWidget`, `BlockAlignment`, `BlockWidth`, and `Size`.
+If you are on Volto 19.0.0-alpha.12 or later, import them from `@plone/volto/components/manage/Widgets/` instead of from VLT.
+
+`ColorContrastChecker` was not part of that move and is still provided by VLT.
 ```
 
-## Creating a Custom Hero Block
+(cover-block-label)=
 
-Let's build a hero block step by step, starting with a basic implementation and then enhancing it with VLT widgets.
+## Creating a Custom Cover Block
+
+Let's build a cover block step by step, starting with a basic implementation and then enhancing it with VLT widgets.
 
 ### Step 1: Create Basic Block Schema
 
-Create `src/components/blocks/myHero/schema.ts`:
+Create `src/components/blocks/Cover/schema.ts`:
 
 ```typescript
-import { defineMessages } from "react-intl";
+import { defineMessages } from 'react-intl';
 
 const messages = defineMessages({
-  hero: {
-    id: "Hero",
-    defaultMessage: "Hero",
+  cover: {
+    id: 'Cover',
+    defaultMessage: 'Cover',
   },
   title: {
-    id: "Title",
-    defaultMessage: "Title",
+    id: 'Title',
+    defaultMessage: 'Title',
   },
   subtitle: {
-    id: "Subtitle",
-    defaultMessage: "Subtitle",
+    id: 'Subtitle',
+    defaultMessage: 'Subtitle',
   },
   backgroundImage: {
-    id: "Background Image",
-    defaultMessage: "Background Image",
+    id: 'Background Image',
+    defaultMessage: 'Background Image',
   },
 });
 
-const heroBlockSchema = (props) => {
+const coverBlockSchema = (props) => {
   const { intl } = props;
 
   return {
-    title: intl.formatMessage(messages.hero),
+    title: intl.formatMessage(messages.cover),
     fieldsets: [
       {
-        id: "default",
-        title: "Default",
-        fields: ["title", "subtitle"],
+        id: 'default',
+        title: 'Default',
+        fields: ['title', 'subtitle'],
       },
       {
-        id: "design",
-        title: "Design",
-        fields: ["backgroundImage"],
+        id: 'design',
+        title: 'Design',
+        fields: ['backgroundImage'],
       },
     ],
     properties: {
       title: {
         title: intl.formatMessage(messages.title),
-        type: "string",
+        type: 'string',
       },
       subtitle: {
         title: intl.formatMessage(messages.subtitle),
-        type: "string",
+        type: 'string',
       },
       backgroundImage: {
         title: intl.formatMessage(messages.backgroundImage),
-        widget: "object_browser",
-        mode: "image",
+        widget: 'object_browser',
+        mode: 'image',
         allowExternals: false,
       },
     },
@@ -284,36 +288,58 @@ const heroBlockSchema = (props) => {
   };
 };
 
-export { heroBlockSchema };
+export { coverBlockSchema };
 ```
 
 ### Step 2: Create View Component
 
-Create `src/components/blocks/myHero/View.tsx`:
+Before writing any markup, note what the block view is **not** responsible for.
+Volto already wraps every block, and under Block Model v3 it wraps it twice:
+
+```html
+<div class="block cover">              <!-- rendered for you -->
+  <div class="block-inner-container">  <!-- rendered for you under BM3 -->
+    ...your markup starts here...
+```
+
+The outer `.block` carries the block's identity and its theme; the inner container carries the width and the alignment.
+This split is what lets a block have a background that behaves independently of its content width, and it is described in full in {ref}`the two-container system <bm3-two-container-label>`.
+
+A block view that renders its own `.block` wrapper therefore produces a duplicate.
+The way to stay correct under both block models is `BlockWrapper` from `@kitconcept/volto-bm3-compat`, which renders the wrappers under Block Model v2 and steps aside under v3, where Volto renders them itself.
+
+Create `src/components/blocks/Cover/View.tsx`:
 
 ```tsx
-import React from "react";
-import cx from "classnames";
-import config from "@plone/volto/registry";
-import { flattenToAppURL, isInternalURL } from "@plone/volto/helpers/Url/Url";
-import type { BlockViewProps } from "@plone/types";
+import config from '@plone/volto/registry';
+import { flattenToAppURL, isInternalURL } from '@plone/volto/helpers/Url/Url';
+import { BlockWrapper } from '@kitconcept/volto-bm3-compat';
+import type { BlockViewProps } from '@plone/types';
+import type { ReactNode } from 'react';
 
-const HeroView = (props: BlockViewProps) => {
-  const { className, style } = props;
-  const { title, subtitle, backgroundImage, url } = props?.data || {};
+// Under block model 2, BlockWrapper renders `.block.cover` and then this
+// ExtraWrapper. Under block model 3 it renders neither, because Volto already
+// emits both. Either way the result is
+// `.block.cover > .block-inner-container > ...`.
+const InnerContainer = (props: { children: ReactNode }) => (
+  <div className="block-inner-container">{props.children}</div>
+);
 
-  const hasImage = backgroundImage?.[0]?.["@id"];
+const CoverView = (props: BlockViewProps) => {
+  const { title, subtitle, backgroundImage } = props?.data || {};
+
+  const hasImage = backgroundImage?.[0]?.['@id'];
 
   let renderedImage = null;
   if (hasImage) {
-    const Image = config.getComponent("Image").component;
+    const Image = config.getComponent('Image').component;
     const imageItem = backgroundImage[0];
 
     if (Image) {
       renderedImage = (
         <Image
           item={{
-            "@id": imageItem["@id"],
+            '@id': imageItem['@id'],
             image_field: imageItem.image_field,
             image_scales: imageItem.image_scales,
           }}
@@ -323,12 +349,11 @@ const HeroView = (props: BlockViewProps) => {
         />
       );
     } else {
+      const src = imageItem['@id'];
       renderedImage = (
         <img
           src={
-            isInternalURL(url?.["@id"])
-              ? `${flattenToAppURL(url["@id"])}/@@images/image`
-              : url?.["@id"]
+            isInternalURL(src) ? `${flattenToAppURL(src)}/@@images/image` : src
           }
           alt=""
           loading="lazy"
@@ -338,51 +363,46 @@ const HeroView = (props: BlockViewProps) => {
   }
 
   return (
-    <div
-      className={cx("block hero", className, { "has-image": hasImage })}
-      style={style}
-    >
-      {hasImage && <div className="hero-image-wrapper">{renderedImage}</div>}
-
-      <div className="hero-content">
-        <div className="hero-text">
-          {title && <h1 className="hero-title">{title}</h1>}
-          {subtitle && <p className="hero-subtitle">{subtitle}</p>}
-        </div>
+    <BlockWrapper {...props} ExtraWrapper={InnerContainer}>
+      {hasImage && <div className="cover-image-wrapper">{renderedImage}</div>}
+
+      <div className="cover-text">
+        {title && <h2 className="cover-title">{title}</h2>}
+        {subtitle && <p className="cover-subtitle">{subtitle}</p>}
       </div>
-    </div>
+    </BlockWrapper>
   );
 };
 
-export default HeroView;
+export default CoverView;
 ```
 
 ### Step 3: Create Edit Component
 
-Create `src/components/blocks/myHero/Edit.tsx`:
+Create `src/components/blocks/Cover/Edit.tsx`:
 
 ```tsx
-import React from "react";
-import { useIntl } from "react-intl";
-import SidebarPortal from "@plone/volto/components/manage/Sidebar/SidebarPortal";
-import { BlockDataForm } from "@plone/volto/components/manage/Form";
-import { heroBlockSchema } from "./schema";
-import HeroView from "./View";
-import type { BlockEditProps } from "@plone/types";
-
-const HeroEdit = (props: BlockEditProps) => {
+import React from 'react';
+import { useIntl } from 'react-intl';
+import SidebarPortal from '@plone/volto/components/manage/Sidebar/SidebarPortal';
+import { BlockDataForm } from '@plone/volto/components/manage/Form';
+import { coverBlockSchema } from './schema';
+import CoverView from './View';
+import type { BlockEditProps } from '@plone/types';
+
+const CoverEdit = (props: BlockEditProps) => {
   const { selected, onChangeBlock, block, data } = props;
   const intl = useIntl();
 
   return (
     <>
-      <HeroView {...props} />
+      <CoverView {...props} />
       <SidebarPortal selected={selected}>
         <BlockDataForm
           {...props}
           data={data}
           block={block}
-          schema={heroBlockSchema({ props, intl })}
+          schema={coverBlockSchema({ props, intl })}
           onChangeBlock={onChangeBlock}
           formData={data}
           onChangeField={(id: string, value: any) => {
@@ -397,80 +417,84 @@ const HeroEdit = (props: BlockEditProps) => {
   );
 };
 
-export default HeroEdit;
+export default CoverEdit;
 ```
 
 ### Step 4: Register the Basic Block
 
-Update `src/config/blocks.ts`:
+Edit `src/config/blocks.ts`. Do not replace the file: it already holds the block themes from the previous chapter.
+Add the imports at the top of the file, and the registration inside the existing `install` function:
 
 ```typescript
-import type { ConfigType } from "@plone/registry";
-import HeroView from "../components/blocks/myHero/View";
-import HeroEdit from "../components/blocks/myHero/Edit";
-import { heroBlockSchema } from "../components/blocks/myHero/schema";
-import heroSVG from "@plone/volto/icons/hero.svg";
+import type { ConfigType } from '@plone/registry';
+import CoverView from '../components/blocks/Cover/View';
+import CoverEdit from '../components/blocks/Cover/Edit';
+import { coverBlockSchema } from '../components/blocks/Cover/schema';
+import coverSVG from '@plone/volto/icons/hero.svg';
 
 export default function install(config: ConfigType) {
   // ... block themes configuration ...
 
-  // Register Hero Block
-  config.blocks.blocksConfig.hero = {
-    id: "hero",
-    title: "Hero",
-    icon: heroSVG,
-    group: "common",
-    view: HeroView,
-    edit: HeroEdit,
+  // Register Cover Block
+  config.blocks.blocksConfig.cover = {
+    id: 'cover',
+    title: 'Cover',
+    icon: coverSVG,
+    group: 'common',
+    view: CoverView,
+    edit: CoverEdit,
     restricted: false,
     mostUsed: true,
-    blockSchema: heroBlockSchema,
+    blockSchema: coverBlockSchema,
     sidebarTab: 1,
-    category: "hero",
   };
 
   return config;
 }
 ```
 
+```{note}
+Give project blocks their own key, and follow the convention every other block in the registry uses: a lowercase single word such as `teaser`, `banner`, or `slider`, reserving camelCase for genuinely multi-word names like `gridBlock`.
+
+The icon is a separate matter. Icon assets are not tied to block names, and {file}`hero.svg` is the one that depicts this layout, so it we will use it in this example.
+```
+
 ### Step 5: Add Basic Block Styles
 
-Create `src/theme/blocks/_hero.scss`:
+The block has no styling fields yet, so this step sets up **structure only**.
+Everything that depends on a widget—the width, the alignment, the theme color—arrives in Step 8, once the fields that produce those properties exist.
 
-```scss
-.block.hero {
-  position: relative;
-  display: flex;
-  width: 100%;
-  max-width: var(--block-width) !important;
-  align-items: center;
-  justify-content: center;
-  background-color: var(--theme-color);
-  color: var(--theme-foreground-color);
-  margin-inline: auto;
+Create `src/theme/blocks/_cover.scss`:
 
-  .hero-content {
+```scss
+.block.cover {
+  .block-inner-container {
     position: relative;
-    z-index: 1;
-    width: 100%;
+    display: flex;
+    overflow: hidden;
+    min-height: 60vh;
+    max-width: var(--default-container-width);
+    align-items: center;
+    padding: 4rem 2rem;
+    margin-inline: auto;
   }
 
-  .hero-text {
+  .cover-text {
+    // Above the background image.
+    position: relative;
+    z-index: 1;
     display: flex;
     width: 100%;
-    height: 100%;
     flex-direction: column;
-    align-items: var(--block-alignment);
     gap: 1rem;
-    text-align: var(--block-alignment);
 
-    .hero-title {
+    .cover-title {
       margin-bottom: $spacing-small;
       font-size: 5rem;
       line-height: 1.1;
     }
 
-    .hero-subtitle {
+    .cover-subtitle {
       margin-bottom: $spacing-small;
       font-size: 2rem;
       line-height: 1.3;
@@ -478,110 +502,127 @@ Create `src/theme/blocks/_hero.scss`:
     }
   }
 
-  &.has-image {
+  &:has(.cover-image-wrapper) {
     color: #fff;
+  }
 
-    .hero-image-wrapper {
-      position: absolute;
-      z-index: 0;
-      inset: 0;
+  .cover-image-wrapper {
+    position: absolute;
+    z-index: 0;
+    inset: 0;
 
-      img {
-        width: 100%;
-        height: 100%;
-        object-fit: cover;
-        opacity: 0.7;
-      }
-
-      &::after {
-        position: absolute;
-        background: rgba(0, 0, 0, 0.4);
-        content: "";
-        inset: 0;
-      }
+    img {
+      width: 100%;
+      height: 100%;
+      object-fit: cover;
+      opacity: 0.7;
     }
 
-    .hero-content {
-      position: relative;
-      z-index: 1;
+    &::after {
+      position: absolute;
+      background: rgb(0 0 0 / 40%);
+      content: '';
+      inset: 0;
     }
   }
 }
 ```
 
-Import in `src/theme/_main.scss`:
+Two decisions worth calling out.
+
+**The width goes on `.block-inner-container`, not on `.block`.**
+That is the two-container split: the outer element is the block's full extent, the inner one is where content is constrained. Putting `max-width` on the outer element instead fights VLT, which already constrains inner containers, and it makes a full-width block impossible.
+
+**`min-height` is load-bearing.**
+The image sits in an absolutely positioned wrapper and contributes no height, so without it a cover with an image collapses to nothing—at which point the alignment control in Step 8 will appear to do nothing, because there is no space to align within.
+
+Import it in `src/theme/_main.scss`:
 
 ```scss
-@import "./blocks/hero";
-@import "./site";
+@import './blocks/button';
+@import './blocks/cover';
+@import './blocks/grid';
+@import './blocks/slider';
+@import './blocks/teaser';
 ```
 
 ### Step 6: Enhance with VLT Widgets
 
-Now let's add VLT's powerful widgets to control block width and alignment. Update the schema file to add the schema enhancer.
+Now let's add VLT's widgets for block width and alignment, by adding a schema enhancer alongside the block schema.
 
-Update `src/components/blocks/myHero/schema.ts`:
+```{important}
+The enhancer below **extends** the styling fieldset; it does not create one.
+`schema.properties.styles` only exists once VLT's `defaultStylingSchema` has run, so this enhancer is meaningful only when composed after it—which is what Step 7 does:
+
+    schemaEnhancer: composeSchema(defaultStylingSchema, coverSchemaEnhancer)
+
+Registered on its own, it throws, because `schema.properties.styles` is `undefined`.
+This is also why the block gets its **Background color** control for free: that field comes from `defaultStylingSchema`, not from anything you write here.
+```
+
+Replace the whole of `src/components/blocks/Cover/schema.ts` with the following. It repeats the schema from Step 1, adds two messages, and exports the new enhancer:
 
 ```typescript
-import { defineMessages } from "react-intl";
+import { defineMessages } from 'react-intl';
+import config from '@plone/volto/registry';
 
 const messages = defineMessages({
-  hero: {
-    id: "Hero",
-    defaultMessage: "Hero",
+  cover: {
+    id: 'Cover',
+    defaultMessage: 'Cover',
   },
   title: {
-    id: "Title",
-    defaultMessage: "Title",
+    id: 'Title',
+    defaultMessage: 'Title',
   },
   subtitle: {
-    id: "Subtitle",
-    defaultMessage: "Subtitle",
+    id: 'Subtitle',
+    defaultMessage: 'Subtitle',
   },
   backgroundImage: {
-    id: "Background Image",
-    defaultMessage: "Background Image",
+    id: 'Background Image',
+    defaultMessage: 'Background Image',
   },
   blockWidth: {
-    id: "Block Width",
-    defaultMessage: "Block Width",
+    id: 'Block Width',
+    defaultMessage: 'Block Width',
   },
   textAlignment: {
-    id: "Text Alignment",
-    defaultMessage: "Text Alignment",
+    id: 'Text Alignment',
+    defaultMessage: 'Text Alignment',
   },
 });
 
-const heroBlockSchema = (props) => {
+const coverBlockSchema = (props) => {
   const { intl } = props;
 
   return {
-    title: intl.formatMessage(messages.hero),
+    title: intl.formatMessage(messages.cover),
     fieldsets: [
       {
-        id: "default",
-        title: "Default",
-        fields: ["title", "subtitle"],
+        id: 'default',
+        title: 'Default',
+        fields: ['title', 'subtitle'],
       },
       {
-        id: "design",
-        title: "Design",
-        fields: ["backgroundImage"],
+        id: 'design',
+        title: 'Design',
+        fields: ['backgroundImage'],
       },
     ],
     properties: {
       title: {
         title: intl.formatMessage(messages.title),
-        type: "string",
+        type: 'string',
       },
       subtitle: {
         title: intl.formatMessage(messages.subtitle),
-        type: "string",
+        type: 'string',
       },
       backgroundImage: {
         title: intl.formatMessage(messages.backgroundImage),
-        widget: "object_browser",
-        mode: "image",
+        widget: 'object_browser',
+        mode: 'image',
         allowExternals: false,
       },
     },
@@ -589,204 +630,172 @@ const heroBlockSchema = (props) => {
   };
 };
 
-// Schema enhancer to add VLT widget styling fields
-const heroSchemaEnhancer = ({ formData, schema, intl }) => {
+// Schema enhancer to add VLT widget styling fields.
+// Only meaningful when composed *after* VLT's `defaultStylingSchema`, which is
+// what creates `schema.properties.styles`.
+const coverSchemaEnhancer = ({ formData, schema, intl }) => {
   // Add custom fields to the styling schema at the beginning
   schema.properties.styles.schema.fieldsets[0].fields = [
-    "blockWidth:noprefix",
-    "align",
+    'align:noprefix',
+    'blockWidth:noprefix',
     ...schema.properties.styles.schema.fieldsets[0].fields,
   ];
 
-  schema.properties.styles.schema.properties["blockWidth:noprefix"] = {
-    widget: "blockWidth",
-    title: intl.formatMessage(messages.blockWidth),
-    default: "default",
+  schema.properties.styles.schema.properties['align:noprefix'] = {
+    widget: 'blockAlignment',
+    title: intl.formatMessage(messages.textAlignment),
+    default: 'center',
+    actions: config.blocks.alignments.map((alignment) => alignment.name),
   };
 
-  schema.properties.styles.schema.properties.align = {
-    widget: "blockAlignment",
-    title: intl.formatMessage(messages.textAlignment),
-    default: "center",
+  schema.properties.styles.schema.properties['blockWidth:noprefix'] = {
+    widget: 'blockWidth',
+    title: intl.formatMessage(messages.blockWidth),
+    default: 'default',
+    actions: config.blocks.widths.map((width) => width.name),
   };
 
   return schema;
 };
 
-export { heroBlockSchema, heroSchemaEnhancer };
+export { coverBlockSchema, coverSchemaEnhancer };
 ```
 
+Two details in that enhancer decide whether it works at all.
+
+**The field names must end in `:noprefix`.**
+As covered in the previous chapter, `align:noprefix` and `align` are different field names.
+VLT registers its style definitions under the literal names `align:noprefix` and `blockWidth:noprefix`, so a field called `align` matches nothing: the `--block-alignment` property is never injected, and the styles in Step 8 that read it silently do nothing.
+The failure is quiet—the buttons still appear in the sidebar, they just have no effect.
+
+Match the names VLT registers, and you inherit its behavior. What the suffix suppresses is the generated `has--align--center` class, and the more your styling is driven by custom properties—as the Cover block's is—the less those classes matter.
+
+**Pass `actions` from `config.blocks`.**
+Both widgets fall back to a built-in list when `actions` is omitted, and those built-in defaults are close to VLT's but not identical—Volto's `full` width resolves to `unset` where VLT's resolves to `100%`.
+Deriving the actions from `config.blocks.alignments` and `config.blocks.widths` keeps the block in step with the theme, and with any width or alignment your project adds.
+
 ### Step 7: Update Block Registration with Schema Enhancer
 
-Update `src/config/blocks.ts` to include the schema enhancer:
+Back in `src/config/blocks.ts`, add the two new imports and the `schemaEnhancer` key to the registration you wrote in Step 4:
 
 ```typescript
-import type { ConfigType } from "@plone/registry";
-import HeroView from "../components/blocks/myHero/View";
-import HeroEdit from "../components/blocks/myHero/Edit";
+import type { ConfigType } from '@plone/registry';
+import CoverView from '../components/blocks/Cover/View';
+import CoverEdit from '../components/blocks/Cover/Edit';
 import {
-  heroBlockSchema,
-  heroSchemaEnhancer,
-} from "../components/blocks/myHero/schema";
-import { composeSchema } from "@plone/volto/helpers/Extensions";
-import { defaultStylingSchema } from "@kitconcept/volto-light-theme/components/Blocks/schema";
-import heroSVG from "@plone/volto/icons/hero.svg";
+  coverBlockSchema,
+  coverSchemaEnhancer,
+} from '../components/blocks/Cover/schema';
+import { composeSchema } from '@plone/volto/helpers/Extensions';
+import { defaultStylingSchema } from '@kitconcept/volto-light-theme/components/Blocks/schema';
+import coverSVG from '@plone/volto/icons/hero.svg';
 
 export default function install(config: ConfigType) {
   // ... block themes configuration ...
 
-  // Register Hero Block
-  config.blocks.blocksConfig.hero = {
-    id: "hero",
-    title: "Hero",
-    icon: heroSVG,
-    group: "common",
-    view: HeroView,
-    edit: HeroEdit,
+  // Register Cover Block
+  config.blocks.blocksConfig.cover = {
+    id: 'cover',
+    title: 'Cover',
+    icon: coverSVG,
+    group: 'common',
+    view: CoverView,
+    edit: CoverEdit,
     restricted: false,
     mostUsed: true,
-    blockSchema: heroBlockSchema,
-    schemaEnhancer: composeSchema(defaultStylingSchema, heroSchemaEnhancer),
+    blockSchema: coverBlockSchema,
+    schemaEnhancer: composeSchema(defaultStylingSchema, coverSchemaEnhancer),
     sidebarTab: 1,
-    category: "hero",
   };
 
   return config;
 }
 ```
 
-### Step 8: Update Styles to Use Widget Values
+`composeSchema` runs its arguments in order, so `defaultStylingSchema` creates the styling fieldset and `coverSchemaEnhancer` then extends it. Reverse them and the second enhancer runs against a schema that has no `styles` property yet.
 
-Update `src/theme/blocks/_hero.scss` to use the CSS custom properties set by the widgets:
+```{tip}
+The same technique adds VLT's theming to a block **you did not write**—one from a third-party add-on, or a core Volto block. The only difference is that such a block may already have a `schemaEnhancer` of its own, which you must preserve:
 
-```scss
-.block.hero {
-  position: relative;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  background-size: cover;
-  background-position: center;
-  background-color: var(--theme-color);
-  color: var(--theme-foreground-color);
-  max-width: var(--block-width) !important;
-  margin-left: auto;
-  margin-right: auto;
-
-  .hero-content {
-    .hero-image-wrapper {
-      img {
-        aspect-ratio: var(--image-aspect-ratio, 16/9);
-        opacity: 0.8;
-      }
-    }
+    config.blocks.blocksConfig.<blockId> = {
+      ...config.blocks.blocksConfig.<blockId>,
+      schemaEnhancer: composeSchema(
+        config.blocks.blocksConfig.<blockId>.schemaEnhancer,
+        defaultStylingSchema,
+      ),
+    };
 
-    .hero-text {
-      position: absolute;
-      display: flex;
-      flex-direction: column;
-      align-items: var(--block-alignment);
-      width: 100%;
-      height: 100%;
-      padding: 4rem;
-      z-index: 2;
-
-      .hero-title {
-        font-size: 5rem;
-        margin-bottom: $spacing-small;
-        line-height: 1;
-      }
-
-      .hero-subtitle {
-        font-size: 3rem;
-        opacity: 0.95;
-        line-height: 1;
-      }
-    }
-  }
-}
 ```
 
-## Integrating Third-Party Blocks
-
-Let's learn how to integrate the `@plone-collective/volto-relateditems-block` into VLT.
-
-### Install the Block
+### Step 8: Update Styles to Use Widget Values
 
-To install the related items block, make sure you are in the `frontend/packages/my-vlt-project` folder, and use the following command:
+The structure from Step 5 stays as it is. This step connects it to the three custom properties that now exist, because the schema enhancers from Steps 6 and 7 are in place: `--block-width`, `--block-alignment`, and `--theme-color`.
 
-```bash
-pnpm install @plone-collective/volto-relateditems-block@latest
-```
+Make these four changes in `src/theme/blocks/_cover.scss`:
 
-Add it to your `package.json` addons (before VLT):
-
-```json
-"addons": [
-  "@eeacms/volto-accordion-block",
-  "@kitconcept/volto-banner-block",
-  "@kitconcept/volto-bm3-compat",
-  "@kitconcept/volto-button-block",
-  "@kitconcept/volto-carousel-block",
-  "@kitconcept/volto-dsgvo-banner",
-  "@kitconcept/volto-heading-block",
-  "@kitconcept/volto-highlight-block",
-  "@kitconcept/volto-introduction-block",
-  "@kitconcept/volto-logos-block",
-  "@kitconcept/volto-separator-block",
-  "@kitconcept/volto-slider-block",
-  "@plonegovbr/volto-social-media",
-  "@plone-collective/volto-relateditems-block",
-  "@kitconcept/volto-light-theme"
-],
-```
+```scss
+// 1. Lift VLT's layout-width cap. See the explanation below.
+#page-document .blocks-group-wrapper > .block.cover {
+  max-width: 100%;
+}
 
-### Enhance the Block Schema
+.block.cover {
+  // 2. The theme's foreground color, set by the Background color control.
+  color: var(--theme-foreground-color);
 
-To add the theme feature to the Related Items block, update `src/config/blocks.ts` to register the `defaultStylingSchema` enhancer:
+  .block-inner-container {
+    position: relative;
+    display: flex;
+    overflow: hidden;
+    min-height: 60vh;
+
+    // 3. Driven by the Block Width control, with the site default as a
+    //    fallback so the block stays sane if the field is ever removed.
+    max-width: var(--block-width, var(--default-container-width));
+    align-items: center;
+    padding: 4rem 2rem;
+    margin-inline: auto;
+
+    // The theme's background. `background`, never `background-color` — see the
+    // warning below.
+    background: var(--theme-color);
+  }
 
-```typescript
-export default function install(config: ConfigType) {
-  // ... previous configuration ...
+  .cover-text {
+    position: relative;
+    z-index: 1;
+    display: flex;
+    width: 100%;
+    flex-direction: column;
 
-  config.blocks.blocksConfig.relatedItems = {
-    ...config.blocks.blocksConfig.relatedItems,
-    schemaEnhancer: defaultStylingSchema,
-  };
+    // 4. Driven by the Text Alignment control.
+    align-items: var(--block-alignment, start);
+    gap: 1rem;
+    text-align: var(--block-alignment, start);
 
-  return config;
+    // ... the rest is unchanged from Step 5 ...
+  }
 }
 ```
 
-### Add Custom Styles
+Because the width and the background both sit on `.block-inner-container`, the Block Width control now resizes the whole visual unit—color, image, and text together—rather than only the text.
 
-Create `src/theme/blocks/_relatedItems.scss`:
+## Checkpoint
 
-```scss
-.block.relatedItems {
-  .inner-container {
-    background: var(--theme-high-contrast-color);
-    padding: 3rem;
-    width: var(--narrow-container-width);
-
-    h2.headline {
-      color: var(--theme-foreground-color);
-    }
+Restart the frontend, then add a Cover block to the Robotarium landing page. Give it the title **Book a robot. Build something.**, a subtitle such as *Twelve units, one afternoon at a time*, and a workshop photo as the background image. Confirm that:
 
-    ul {
-      color: var(--theme-foreground-color);
-      li a {
-        color: var(--link-foreground-color);
-      }
-    }
-  }
-}
+- The block appears in the block chooser, listed as **Cover**.
+- The **Styling** tab of the sidebar shows **Alignment** and **Block Width** controls.
+- Changing the alignment moves the title and subtitle, and changing the width resizes the block. If the controls appear but nothing moves, check that the field names end in `:noprefix`.
+- Setting the width to **Full Width** takes the block edge to edge, background image included.
+
+```{seealso}
+A block can also offer more than one rendering of the same data, as the Listing block does with its variations.
+That is covered in the next chapter, where the Robotarium gets a **Robot Fleet** listing variation with its own card layout and per-item actions.
 ```
 
-Import it in `_main.scss`:
+## Further Reading
 
-```scss
-@import "./blocks/hero";
-@import "./blocks/relatedItems";
-@import "./site";
-```
+- [Widgets reference](https://volto-light-theme.readthedocs.io/reference/widgets.html)
+- [Develop add-ons for VLT](https://volto-light-theme.readthedocs.io/how-to-guides/develop-add-ons.html)
+- [Image aspect ratio](https://volto-light-theme.readthedocs.io/reference/image-aspect-ratio.html)
diff --git a/docs/customizing-volto-light-theme/concepts.md b/docs/customizing-volto-light-theme/concepts.md
index 1a3aa1049..f3cd98283 100644
--- a/docs/customizing-volto-light-theme/concepts.md
+++ b/docs/customizing-volto-light-theme/concepts.md
@@ -9,6 +9,22 @@ myst:
 
 # Foundation, Concepts & Project Setup
 
+## The Project
+
+Rather than theme an abstract site, this training builds one: **the Robotarium**, a neighborhood workshop that lends robots the way a library lends books. Members browse the fleet, check what is charged and available, and book a unit for the afternoon.
+
+It is a small site with an ordinary shape—a fleet to list, a workshop to describe, and a way to visit—which is exactly what makes it useful here. Every VLT feature the training covers earns its place by solving something the Robotarium actually needs:
+
+| The site needs | You will learn |
+| --- | --- |
+| A look that is its own, not the default | Design tokens, color system, block themes |
+| A full-width opening on the landing page | Building a custom block with VLT's widgets |
+| A fleet listing showing charge levels | Summary components and listing variations |
+| A booking button on each robot | The Card primitive and its Actions slot |
+| A sign-up form above the footer | Slots |
+
+The project add-on is called `robotarium` throughout. If you would rather build something else, every step works the same with your own name substituted; only the copy changes.
+
 ## Volto Light Theme Core Concepts
 
 Volto Light Theme (VLT) is a customizable theme built for the Volto frontend of the Plone CMS. It provides a foundation that aims to solve many common design challenges, while remaining flexible enough for customization. It's particularly valuable because it is based on real-world experience, while simultaneously embodying the Volto vision for the future. This module will help you understand the core concepts in VLT and create a mental map of its parts.
@@ -48,6 +64,25 @@ The main color properties for a project using VLT are:
 --accent-foreground-color: #000;
 ```
 
+These six properties are not declared as plain custom properties.
+VLT registers them with the CSS [`@property`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@property) at-rule, which declares their type and their default value in one place:
+
+```scss
+@property --primary-color {
+  inherits: true;
+  initial-value: #fff;
+  syntax: '<color>';
+}
+```
+
+Registering them buys three things that matter for a theme:
+
+- The `initial-value` is the default, so the property always resolves to a valid color even when nothing has set it.
+- The `<color>` syntax makes the value typed, so an invalid value is rejected instead of silently cascading.
+- Typed properties can be interpolated, so transitions and `color-mix()` behave predictably.
+
+You override them the same way as any other custom property, by assigning to them in `:root`.
+
 ### Semantic Color Properties
 
 As an additional layer on top of the main color properties, we have set in place some semantic custom properties for the basic layout sections. As a default they use the values from the main color variables, but they can be detached if desired by setting new color values. However, leaving these color relationships as they are helps create a cohesive final design:
@@ -57,7 +92,7 @@ As an additional layer on top of the main color properties, we have set in place
 --header-background: var(--primary-color);
 --header-foreground: var(--primary-foreground-color);
 
-//Footer
+// Footer
 --footer-background: var(--secondary-color);
 --footer-foreground: var(--secondary-foreground-color);
 
@@ -74,7 +109,18 @@ As an additional layer on top of the main color properties, we have set in place
 --search-foreground: var(--accent-foreground-color);
 
 // Link color
---link-foreground-color: var(--link-color);
+--link-color: #0070a2;
+```
+
+Links are the one exception to the pattern above.
+By default `<a>` elements inherit `--theme-foreground-color`, so they take the foreground color of whatever block theme they sit in, rather than a color of their own.
+VLT ships `--link-foreground-color` as an opt-in: define it in your project to give links a distinct color everywhere.
+
+```scss
+:root {
+  // Turn links into a different color than the theme foreground color
+  --link-foreground-color: var(--link-color);
+}
 ```
 
 ### Block Themes
@@ -83,7 +129,7 @@ VLT includes a block theme system that enables individual blocks to use distinct
 
 **The four core block theme variables:**
 
-- `--theme-color`: Primary background color — the most visible color in the block
+- `--theme-color`: Primary background color—the most visible color in the block
 - `--theme-high-contrast-color`: Secondary background color for nested elements (e.g., cards within a block) to create visual separation from the main background
 - `--theme-foreground-color`: Default text and icon color
 - `--theme-low-contrast-foreground-color`: Subdued text color for secondary content like placeholders or helper text
@@ -117,7 +163,18 @@ config.blocks.themes = [
 ];
 ```
 
-Users select block themes through the `themeColorSwatch` widget in the block sidebar. This widget renders colored buttons using each theme's `--theme-color` value, allowing visual theme selection.
+Users select a block theme from the **Background color** control in the block sidebar's **Styling** tab.
+VLT's `defaultStylingSchema` adds a `theme` field to the block's schema and renders it with the `color_picker` widget, which draws one button per configured theme using that theme's `--theme-color` as the button color.
+
+```{note}
+`color_picker` is a legacy name for what is really a swatch picker, and VLT registers the very same `ColorSwatch` component under both `color_picker` and `colorSwatch`.
+VLT's own source says as much, with a rename planned for Volto 19.
+
+Do not confuse it with two similarly named widgets:
+
+- `colorPicker` is a different widget entirely—a full color input with a contrast checker—used for the site-wide colors that the backend behaviors expose.
+- `themeColorSwatch` is registered by VLT but currently is not used by any schema VLT ships.
+```
 
 ### Container Width System
 
@@ -130,11 +187,22 @@ VLT uses three types of container widths:
 --narrow-container-width: 620px; // optimal readability for text
 ```
 
-The VLT `BlockWidthWidget` stores the value of the custom property `--block-width` so that it can be used by the StyleWrapper when injecting styles into the markup.
+Those three are the site-wide scale. Individual blocks never read them directly. Instead, each block carries a `--block-width` property that points at one of them, and the `blockWidth` widget is what chooses the target:
+
+| Token stored | `--block-width` becomes | Resulting width |
+| --- | --- | --- |
+| `narrow` | `var(--narrow-container-width)` | 620px |
+| `default` | `var(--default-container-width)` | 940px |
+| `layout` | `var(--layout-container-width)` | 1440px |
+| `full` | `100%` | edge to edge |
+
+The indirection is what makes the scale worth having. A block's stylesheet only ever writes `max-width: var(--block-width)`, so it never needs to know which of the three it was handed, and changing `--default-container-width` in one place moves every block set to `default`. Only `full` steps outside the scale, which is why it resolves to a plain `100%` rather than to a container width.
+
+The section on style fields below explains how the stored token becomes that value.
 
 ### Block Alignment
 
-The `BlockAlignmentWidget` takes advantage of the StyleWrapper by setting the `--block-alignment` property. The three default options are:
+The `blockAlignment` widget works the same way, storing one of `left`, `center`, or `right` and resolving it to `--block-alignment`. The three tokens map to these values:
 
 ```scss
 --align-left: start;
@@ -142,9 +210,128 @@ The `BlockAlignmentWidget` takes advantage of the StyleWrapper by setting the `-
 --align-right: end;
 ```
 
+### Style Fields and the `:noprefix` Convention
+
+Width and alignment are both **style fields**, and every style field follows the same two-step process: store a token, then resolve that token to a style object at render time.
+
+What a block actually saves is short. A block set to narrow width and left alignment stores this in its `styles` object:
+
+```json
+{
+  "blockWidth:noprefix": "narrow",
+  "align:noprefix": "left"
+}
+```
+
+Only the tokens are stored—no CSS, no custom property values. Resolution happens when the block renders:
+
+1. For each key in `styles`, VLT looks up a `styleFieldDefinition` utility registered under **that exact key**.
+2. The utility returns a list of style definitions. For `blockWidth:noprefix` that list is `config.blocks.widths`.
+3. VLT finds the definition whose `name` matches the stored token and takes its `style` object. For `narrow`, that is `{ '--block-width': 'var(--narrow-container-width)' }`.
+4. The StyleWrapper injects that object as an inline style on the block.
+
+Storing tokens rather than values is what makes the system re-themeable. Change what `narrow` means in `config.blocks.widths` and every block already set to `narrow` follows, because the content only ever recorded the word.
+
+Separately, the StyleWrapper turns each style field into a CSS class.
+By default it prefixes the class with the field name, so a field named `align` with the value `center` produces `has--align--center`.
+
+A field name ending in `:noprefix` opts out of that prefixing.
+VLT uses this suffix for its own style fields, and registers the matching style definitions under the same literal name:
+
+```typescript
+config.registerUtility({
+  name: 'align:noprefix',
+  type: 'styleFieldDefinition',
+  method: ({ data }) =>
+    config.blocks.blocksConfig?.[data?.['@type'] ?? '']?.alignments ||
+    config.blocks.alignments,
+});
+```
+
+The suffix is part of the field name, not decoration.
+A field named `align` and a field named `align:noprefix` are two different fields: only the second one matches the utility above, and only the second one gets its CSS custom properties injected.
+The three style fields VLT defines this way are `align:noprefix`, `blockWidth:noprefix`, and `size:noprefix`.
+
+
+### Generated Block Classes
+
+Beyond the style fields, VLT registers a set of `styleClassNameExtenders` that inspect each block's position in the page and inject extra classes on it.
+This is what lets the theme control vertical spacing between blocks from CSS alone, without a block needing to know anything about its neighbors.
+
+The classes available on every block are:
+
+| Class | Injected when |
+| --- | --- |
+| `next--is--${type}` | the following block is of that type |
+| `previous--is--same--block-type` | the preceding block has the same type |
+| `next--is--same--block-type` | the following block has the same type |
+| `is--first--of--block-type` | the preceding block has a different type |
+| `is--last--of--block-type` | the following block has a different type |
+| `has--headline` | the block has a headline, or follows a heading block |
+| `previous--has--same--backgroundColor` | the preceding block uses the same theme |
+| `next--has--same--backgroundColor` | the following block uses the same theme |
+| `previous--has--different--backgroundColor` | the preceding block uses a different theme |
+| `next--has--different--backgroundColor` | the following block uses a different theme |
+| `has--block-width--${width}` | always, from the `blockWidth:noprefix` field |
+| `has--block-alignment--${alignment}` | always, from the `align:noprefix` field |
+| `has--background-color--${theme}` | always, from the block's selected theme |
+
+You will see these used throughout VLT's own stylesheets, and in the examples later in this training.
+A typical use is collapsing the gap between two adjacent blocks that share a background, so the pair reads as one band of color:
+
+```scss
+.block.listing {
+  &.next--has--same--backgroundColor.next--is--same--block-type {
+    .listing-item:last-child {
+      padding-bottom: 0;
+      border-bottom: none;
+    }
+  }
+}
+```
+
+Because the extenders are registered in configuration, a project can add its own to inject any class it needs.
+
 ## Create a New Project with Cookieplone
 
-We recommend creating your Plone project with **Cookieplone**. Our comprehensive documentation provides step-by-step guidance to help you get started. For detailed installation instructions, visit our [Cookieplone guide](https://6.docs.plone.org/install/create-project-cookieplone.html).
+When creating your Plone project with **Cookieplone**, choose template **1, "Volto Project"**, then answer the prompts.
+
+The defaults are fine for almost everything, but two answers matter for the rest of this training:
+
+| Prompt | Default | Answer |
+| --- | --- | --- |
+| `[1/19] Project Title` | `Project Title` | `robotarium` |
+| `[3/19] Project Slug` | `robotarium` | accept |
+| `[8/19] Plone Version` | `6.2.1` | accept |
+| `[9/19] Volto Version` | `19.4.0` | accept |
+| `[10/19] Python Package Name` | `robotarium` | accept |
+| `[11/19] Volto Addon Name` | `volto-robotarium` | **`robotarium`** |
+| everything else | | accept |
+
+```{important}
+This is where the project gets its name.
+The Project Title you type at `[1/19]` becomes the project slug, the output folder, and the Python package name, and it is what every path in this training refers to.
+
+Pay particular attention to `[11/19] Volto Addon Name`: Cookieplone offers `volto-robotarium`, prefixed with `volto-`.
+This training uses `robotarium`, so override that default.
+If you accept the default instead, or build something other than a Robotarium, every path below of the form {file}`frontend/packages/robotarium/…` becomes {file}`frontend/packages/<your addon name>/…`.
+```
+
+You should end up with this shape:
+
+```console
+robotarium/
+├── Makefile
+├── backend/
+│   ├── pyproject.toml
+│   └── src/robotarium/
+└── frontend/
+    ├── mrs.developer.json
+    ├── volto.config.js
+    └── packages/robotarium/     <- your project add-on
+```
+
+For more detail, see the [Cookieplone guide](https://6.docs.plone.org/install/create-project-cookieplone.html).
 
 ## Installing Volto Light Theme
 
@@ -160,7 +347,7 @@ If you need a stable release instead, use the latest 7.x version of both package
 
 ### Step 1: Install VLT and Recommended Block Add-ons
 
-VLT is installed like any other Volto add-on, as a dependency of your project add-on in {file}`frontend/packages/my-vlt-project/package.json`:
+VLT is installed like any other Volto add-on, as a dependency of your project add-on in {file}`frontend/packages/robotarium/package.json`:
 
 ```json
 {
@@ -173,13 +360,13 @@ VLT is installed like any other Volto add-on, as a dependency of your project ad
 From the root of your project, you can let pnpm add it to the workspace package for you:
 
 ```bash
-pnpm --filter my-vlt-project add @kitconcept/volto-light-theme@alpha
+pnpm --filter robotarium add @kitconcept/volto-light-theme@alpha
 ```
 
 Volto Light Theme supports all core blocks, and it also supports blocks coming from a set of recommended add-ons that provide the basic blocks for your website.
 Including them is not required, and you can pick only the ones you want to use.
 
-Since VLT 8.0.0, these recommended add-ons are no longer declared as `peerDependencies` of VLT, so you have to install them yourself as dependencies of your project add-on in {file}`frontend/packages/my-vlt-project/package.json`:
+Since VLT 8.0.0, these recommended add-ons are no longer declared as `peerDependencies` of VLT, so you have to install them yourself as dependencies of your project add-on in {file}`frontend/packages/robotarium/package.json`:
 
 ```json
 {
@@ -233,14 +420,15 @@ Installing a package is not enough: it also has to be declared as a Volto add-on
 
 -**Important:** VLT must be the last addon in the list to ensure proper style cascade. Your project addon will still be the last applied if defined in `volto.config.js`.
 
-Run `pnpm install` from the project root after editing {file}`package.json` by hand, so that the workspace picks up the new dependencies.
+Don't install anything yet.
+The backend needs an edit too, and a single command at the end installs both—see {ref}`vlt-install-step-3`.
 
 ### Step 2: Configure VLT as the Theme Provider
 
 VLT is not only a regular add-on, it is also a theme add-on, so it has to be declared as the theme of your project.
 How you do that depends on your Volto version.
 
-For Volto 18.29.1 or later, and 19.0.0-alpha.10 or later, declare it with the `theme` key of your project add-on {file}`frontend/packages/my-vlt-project/package.json`, next to the `addons` key:
+For Volto 18.29.1 or later, and 19.0.0-alpha.10 or later, declare it with the `theme` key of your project add-on {file}`frontend/packages/robotarium/package.json`, next to the `addons` key:
 
 ```json
 {
@@ -252,10 +440,12 @@ For Volto 18.29.1 or later, and 19.0.0-alpha.10 or later, declare it with the `t
 }
 ```
 
-For older Volto versions, open the {file}`volto.config.js` file in your `frontend` folder and declare the theme there:
+Cookieplone already generates both keys for you, as `"addons": []` and `"theme": ""`, so this is an edit rather than something you add from scratch.
+
+For older Volto versions, open the {file}`volto.config.js` file in your `frontend` folder and declare the theme there instead:
 
 ```javascript
-const addons = ["my-vlt-project"];
+const addons = ["robotarium"];
 const theme = "@kitconcept/volto-light-theme";
 
 module.exports = {
@@ -268,11 +458,11 @@ You'll need to restart your Plone frontend to see the changes.
 
 That's it! Your project should now be using Volto Light Theme with its additional blocks and components.
 
-### Step 3: Install Backend Package
+(vlt-install-step-3)=
 
-In your backend folder, install the Python package for site customization behaviors.
+### Step 3: Add the Backend Package and Install Everything
 
-Edit `backend/pyproject.toml` and add to the dependencies array:
+Edit {file}`backend/pyproject.toml` and add `kitconcept.voltolighttheme` to the dependencies array:
 
 ```toml
 dependencies = [
@@ -284,15 +474,15 @@ dependencies = [
 ]
 ```
 
-Then install the dependency from your backend folder:
+Both manifests are now edited, so install the whole project in one step, from the project root:
 
 ```bash
 make install
 ```
 
-### Step 4: Install the Backend Add-on
+### Step 4: Start the Servers and Install the Backend Add-on
 
-Start your development environment:
+Start your development environment, from the project root, in two terminals:
 
 ```bash
 # Terminal 1 - Backend
@@ -310,43 +500,150 @@ Once the frontend is running:
 
 ### Step 5: Activate Behaviors for Plone Site
 
-To enable site customization through the UI:
+The backend add-on ships five behaviors. None of them is enabled automatically, because each one adds fields to the Plone Site edit form and you should opt into the ones you want.
+
+| Behavior | Shown in the Behaviors tab as | What it adds |
+| --- | --- | --- |
+| `voltolighttheme.header` | Header customizations for sites/subsites | Site logo, complementary logo, fat menu toggle, intranet header, header actions |
+| `voltolighttheme.theme` | Theme colors customizations for sites/subsites | Five color fields for the navigation, fat menu, and footer—see below |
+| `voltolighttheme.footer` | Footer customizations for sites/subsites | Footer links, footer logos and their size, colophon text |
+| `kitconcept.footer` | kitconcept specific footer customizations | The additional footer arrangement used by kitconcept distributions |
+| `kitconcept.sticky_menu` | Sticky menu | A menu fixed to the right side of the screen |
+
+To activate them:
 
 1. Go to http://localhost:3000/controlpanel/dexterity-types/Plone%20Site
-2. In the "Behaviors" tab, activate the desired behaviors
+2. In the "Behaviors" tab, tick the behaviors from the table above that you want
 3. Click "Save"
 
-These behaviors let you customize the header, footer, and theme of your Plone site with knobs on the content type they are applied to, either the Plone site or a subsite.
-See the [site customization guide](https://volto-light-theme.readthedocs.io/conceptual-guides/site-customization.html) for the details of each behavior.
+The first three are the ones this training uses. Enable all five if you want to see everything the add-on offers.
+
+These behaviors put the knobs on the content type they are applied to, so applying them to the Plone Site configures the whole site, and applying them to a subsite configures that branch instead.
+
+#### What the theme behavior actually does
+
+The behavior adds five empty, optional fields to the edit form, each rendered with the `colorPicker` widget:
+
+| Field | Label in the form | Custom property it sets |
+| --- | --- | --- |
+| `header_foreground` | Navigation Text Color | `--header-foreground` |
+| `accent_foreground_color` | Fat Menu / Breadcrumbs Text Color | `--accent-foreground-color` |
+| `accent_color` | Fat Menu Background Color | `--accent-color` |
+| `secondary_foreground_color` | Footer Font Color | `--secondary-foreground-color` |
+| `secondary_color` | Footer Background Color | `--secondary-color` |
+
+Note that there is no primary color pair here: `primary_color` exists in VLT's frontend color map but is deliberately commented out of the behavior's fieldset.
+
+```{important}
+Those declarations land in `:root` from a tag in the document head, at the same specificity as the design tokens you will define in the next chapter.
+If you set `--accent-color` in your project's stylesheet **and** an editor fills in Fat Menu Background Color, the editor's value is the one that applies.
+That is the intended division of labour—the behaviors exist so that editors can override the theme—but it does mean these five properties are not yours to fix from CSS once the behavior is active.
+```
+
+```{note}
+Behaviors can be added in new releases, and this table reflects `kitconcept.voltolighttheme` 8.0.0a31.
+The authoritative list is the behavior registration in the add-on itself, at {file}`backend/src/kitconcept/voltolighttheme/behaviors/configure.zcml` in the [VLT repository](https://github.com/kitconcept/volto-light-theme).
+See the [site customization guide](https://volto-light-theme.readthedocs.io/conceptual-guides/site-customization.html) for what each field does.
+```
 
 Now your project should have the VLT Site configurations available.
 
 ## File Structure Setup
 
-Let's set up the recommended file structure. In your project add-on's `src` folder, create the following structure:
+Let's set up the recommended file structure in your project add-on's `src` folder.
+Cookieplone already gave you some of it—`index.ts` and `config/settings.ts` exist and have content, so you are filling in the gaps rather than starting from nothing:
 
 ```console
 src/
 ├── components/
-│   └── blocks/
+│   └── blocks/          # new
 ├── config/
-│   ├── settings.ts
-│   └── blocks.ts
-├── index.ts
-└── theme/
+│   ├── settings.ts      # exists, generated with your language settings
+│   └── blocks.ts        # new
+├── index.ts             # exists, generated with applyConfig()
+└── theme/               # new
     ├── blocks/
-    ├── _main.scss
-    └── _site.scss
+    ├── _variables.scss
+    └── _main.scss
 ```
 
-Create the files in `frontend/paackages/my-vlt-project` :
+From {file}`frontend/packages/robotarium/src`:
 
 ```bash
-cd src
 mkdir -p components/blocks config theme/blocks
-touch config/settings.ts config/blocks.ts
-touch index.ts
-touch theme/_main.scss theme/_site.scss
+touch config/blocks.ts theme/_variables.scss theme/_main.scss
+```
+
+```{warning}
+Do not overwrite the generated {file}`index.ts` and {file}`config/settings.ts`.
+The generated `settings.ts` holds your `isMultilingual`, `supportedLanguages`, and `defaultLanguage` values, and `index.ts` already wires it up.
+Every later step in this training that shows one of these two files is showing an **edit**, not a replacement.
 ```
 
 Remember that if you add new files to your project, it will be necessary to restart your Plone frontend.
+
+### The Two Theme Insertion Points
+
+Two of those filenames are load-bearing.
+Volto scans every add-on for {file}`theme/_variables.scss` and {file}`theme/_main.scss`, and injects whichever it finds into the theme's stylesheet at two different points:
+
+| File | Injected | Use it for |
+| --- | --- | --- |
+| {file}`theme/_variables.scss` | **before** VLT's own variables | the few SCSS variables VLT compiles with |
+| {file}`theme/_main.scss` | **after** all of VLT's styles | everything else, including all your custom properties |
+
+The order is what makes each one useful.
+No other filename is special—`theme/blocks/` and anything else you add are ordinary partials that become part of the build only because {file}`_main.scss` imports them.
+
+```{note}
+Volto skips these two files for whichever add-on is registered as the `theme`.
+They work for {file}`robotarium` precisely because VLT, not your project, is the theme add-on.
+```
+
+#### Prefer CSS custom properties
+
+Almost all of your theming should be CSS custom properties written in {file}`_main.scss`, not SCSS variables.
+
+VLT is built as a custom-property system: the color pairs, the semantic properties, the container widths, and the block themes are all custom properties, resolved in the browser. That is what makes them overridable per block, per section, and at runtime—a block theme works by re-declaring `--theme-color` on one block, which no build-time variable could do. Setting your design tokens as custom properties in `:root` is the normal path, and it is what the next chapter does:
+
+```scss
+// src/theme/_main.scss
+:root {
+  --primary-color: #10131a;
+  --accent-color: #d8f24e;
+  --link-color: #2f5fd8;
+}
+```
+
+{file}`_variables.scss` is the narrow exception, for values VLT **computes with at build time**. VLT declares its SCSS variables with `!default`, so each one applies only when nothing has already set it. Since {file}`_variables.scss` is injected first, anything you assign there wins—and it is the *only* place they can be changed, because by the time {file}`_main.scss` is injected, VLT's stylesheets have already been compiled:
+
+```scss
+// src/theme/_variables.scss
+$tablet-breakpoint: 900px;
+$default-container-width: 1120px;
+```
+
+Two kinds of value belong there:
+
+- **Breakpoints**, which cannot be custom properties at all, since media queries cannot read them.
+- **The container widths**, which are subtler and worth understanding.
+
+The rule of thumb: custom properties for anything meant to vary per block, per section, or at runtime—which is nearly everything, and all of the color system. SCSS variables only for the handful of values VLT compiles into media queries and mixins.
+
+## Checkpoint
+
+Restart both servers and confirm the install landed before moving on. Most trouble in later chapters traces back to one of these:
+
+- The site at http://localhost:3000 renders in VLT's styling, not Volto's default Pastanaga theme. If it looks unchanged, VLT is registered as an add-on but not as the `theme`.
+- Editing a page and selecting a block shows a **Background color** control in the sidebar's **Styling** tab. This confirms VLT's block configuration is applied.
+- The add-ons control panel lists **Volto Light Theme** as installed, and the Plone Site content type shows the `voltolighttheme` behaviors as active.
+- Adding an empty {file}`src/theme/_main.scss` with a single obvious rule, such as `body { border-top: 4px solid red; }`, actually shows that border. If it does not, your add-on is not being picked up as a theme add-on, and no amount of CSS in later chapters will apply.
+
+## Further Reading
+
+This training covers the parts of VLT you need to build a project. The theme's own documentation goes deeper on each topic:
+
+- [Color system](https://volto-light-theme.readthedocs.io/conceptual-guides/color-system.html)
+- [Layout](https://volto-light-theme.readthedocs.io/conceptual-guides/layout.html)
+- [Vertical spacing](https://volto-light-theme.readthedocs.io/conceptual-guides/vertical-spacing.html)
+- [Install guide](https://volto-light-theme.readthedocs.io/how-to-guides/install.html)
diff --git a/docs/customizing-volto-light-theme/design-system-implementation.md b/docs/customizing-volto-light-theme/design-system-implementation.md
index ff014bf02..643b98ae6 100644
--- a/docs/customizing-volto-light-theme/design-system-implementation.md
+++ b/docs/customizing-volto-light-theme/design-system-implementation.md
@@ -9,6 +9,10 @@ myst:
 
 # Design System Implementation & Theming
 
+The Robotarium has a look: workshop teal, a technical typeface, and surfaces that read like painted metal. This chapter turns that into a working theme.
+
+Nothing here is specific to robots. The steps are the ones you follow for any design handed to you—pull the decisions out of it, express them as tokens, and let VLT's components pick them up.
+
 ## Extracting Design Tokens
 
 When working with a given design, systematically extract design decisions. Identify:
@@ -44,25 +48,55 @@ VLT has migrated to use standardized color definitions. These use CSS properties
 
 ### Step 1: Add Font Files
 
-If you're using custom fonts, add the font files to your theme directory. Create a `fonts` folder in your theme directory and place your font files there:
+If you're using custom fonts, add the font files to your theme directory.
+The Robotarium uses [Chakra Petch](https://fonts.google.com/specimen/Chakra+Petch); from {file}`frontend/packages/robotarium/src/theme`:
+
+```bash
+mkdir -p fonts/Chakra_Petch
+```
+
+at the end, it should look like:
 
 ```
 src/theme/fonts/Chakra_Petch/
   ├── ChakraPetch-Regular.ttf
-  ├── ChakraPetch-Bold.ttf
-  └── ... (other font weights/styles)
+  └── ChakraPetch-Bold.ttf
 ```
 
 This ensures the font files are bundled with your theme and can be referenced in your SCSS files.
 
-### Step 2: Create _site.scss
+### Step 2: Override SCSS Variables
+
+Some of VLT's design decisions are SCSS variables rather than CSS custom properties. Those belong in {file}`src/theme/_variables.scss`:
+
+```scss
+// src/theme/_variables.scss
+$default-container-width: 1120px;
+$spacing-large: 80px;
+```
+
+VLT declares its variables with `!default`, so whatever you assign here wins.
+It also derives the matching CSS custom properties from them, which means setting `$default-container-width` here updates `--default-container-width` too. You do not need to set both.
+
+### Step 3: Define Your Design Tokens
 
-In `src/theme/_site.scss`, define your color variables, custom properties and block-specific styles:
+In {file}`src/theme/_main.scss`, declare the fonts and the CSS custom properties that carry your design:
 
 ```scss
 @font-face {
   font-family: 'Chakra Petch';
   src: url('./fonts/Chakra_Petch/ChakraPetch-Regular.ttf') format('truetype');
+  font-weight: 400;
+  font-style: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'Chakra Petch';
+  src: url('./fonts/Chakra_Petch/ChakraPetch-Bold.ttf') format('truetype');
+  font-weight: 700;
+  font-style: normal;
+  font-display: swap;
 }
 
 :root {
@@ -71,12 +105,18 @@ In `src/theme/_site.scss`, define your color variables, custom properties and bl
   --accent-foreground-color: #fff;
   --secondary-color: #afcac8;
 
-  // Typography
-  --text-base: 1.15rem;
+  // Typography. VLT reads the font through
+  // `$page-font: var(--custom-main-font, $page-font-template)`.
   --custom-main-font: 'Chakra Petch', sans-serif;
-  --line-height-factor: 1.5;
 
-  // Gradients for header/footer
+  // Give links a color of their own instead of the theme foreground color
+  --link-foreground-color: #157a7a;
+
+  // Breadcrumbs
+  --breadcrumbs-background: var(--background, #fff);
+  --breadcrumbs-foreground: var(--secondary-foreground-color, #3b5759);
+
+  // Gradients for header and footer
   --header-background: linear-gradient(
     -3deg,
     var(--background, #fff) 0%,
@@ -104,106 +144,120 @@ In `src/theme/_site.scss`, define your color variables, custom properties and bl
   );
 
   --fatmenu-foreground: #fff;
+}
+```
 
-  // Container widths (customized)
-  --default-container-width: 1440px;
-  --layout-container-width: 90%;
+Notice that the header and footer gradients are assigned to the same `--header-background` and `--footer-background` properties you saw in the previous chapter.
+Because VLT reads those properties rather than hard-coded colors, a gradient works everywhere a flat color would, with no component changes.
 
-  // Link color
-  --link-foreground-color: #157a7a;
+Setting a font is a good example of the "prefer custom properties" rule from the previous chapter: you do not shadow VLT's typography stylesheets, you set the one property they already read.
 
-  // Breadcrumbs
-  --breadcrumbs-background: var(--background, #fff);
-  --breadcrumbs-foreground: var(--secondary-foreground-color, #3b5759);
+Site-wide rules that are not tokens go in the same file, outside `:root`:
 
-  .breadcrumbs {
-    border-bottom: 1px solid #afcac8;
+```scss
+.breadcrumbs {
+  border-bottom: 1px solid var(--secondary-color);
+}
+
+// Let the first block sit flush with the header
+#page-document,
+#page-edit,
+#page-add {
+  .blocks-group-wrapper:first-child {
+    padding-top: 0;
   }
+}
 
-  // Block-specific styles
-  #page-document,
-  #page-edit,
-  #page-add {
-    .blocks-group-wrapper:first-child {
-      padding-top: 0;
+// Match the theme swatch in the sidebar to the custom "charging bay" theme
+#sidebar {
+  .color-swatch-widget .color-swatch-option-handler.charging-bay {
+    background: linear-gradient(135deg, var(--secondary-color) 0%, #fff 100%);
+  }
+}
+```
 
-    }
-    .block {
-
-      &.__button {
-        .button {
-          button {
-            padding: 1rem;
-          }
-        }
-      }
+```{warning}
+Declare custom properties inside `:root`, but keep normal rules outside it.
+Nesting a selector such as `#page-document` inside `:root` compiles to `:root #page-document`, which adds specificity you will have to fight later.
+```
 
-      &.__button {
-        .ui.button:hover {
-          --theme-color: #fff;
-        }
-      }
+### Step 4: Add Block-Specific Styles
 
-      &.slider {
-        .teaser-item-title {
-          background: rgba(255, 255, 255, 0.1);
-          color: var(--theme-foreground-color) !important;
-          backdrop-filter: blur(20px) saturate(110%);
-          -webkit-backdrop-filter: blur(20px) saturate(180%);
-          box-shadow:
-            0 8px 32px 0 rgba(31, 135, 125, 0.1),
-            inset 0 0 0 1px rgba(255, 255, 255, 0.1);
-        }
-      }
+Keep per-block styles in their own partials under {file}`src/theme/blocks/`, one file per block.
+This keeps them easy to find and stops {file}`_main.scss` from turning too complex.
 
-      &.gridBlock {
-        .four {
-          .slate:not(.inner) {
-            padding: 2.5rem;
-            padding-top: 4rem !important;
-            backdrop-filter: blur(20px) saturate(110%);
-            -webkit-backdrop-filter: blur(20px) saturate(180%);
-            box-shadow:
-              0 8px 32px 0 rgba(31, 135, 125, 0.1),
-              inset 0 0 0 1px rgba(255, 255, 255, 0.1);
-          }
-        }
-      }
 
-      &.teaser {
-        .card {
-          .card-inner {
-            .card-summary {
-              padding: $spacing-large;
-            }
-          }
-        }
+```scss
+// src/theme/blocks/_button.scss
+body .block.__button {
+  > .button.container,
+  > .block-inner-container {
+    a,
+    button {
+      padding: 1rem;
+      transition:
+        background 0.2s ease,
+        color 0.2s ease;
+
+      &:hover,
+      &:active,
+      &:focus {
+        background: var(--accent-color);
+        color: var(--accent-foreground-color);
       }
     }
+  }
+}
+```
 
+```scss
+// src/theme/blocks/_slider.scss
+.block.slider .teaser-item .teaser-item-title {
+  background: rgb(255 255 255 / 10%);
+  backdrop-filter: blur(20px) saturate(110%);
+  box-shadow:
+    0 8px 32px 0 rgb(31 135 125 / 10%),
+    inset 0 0 0 1px rgb(255 255 255 / 10%);
+  color: var(--theme-foreground-color);
+}
+```
 
-  }
+```scss
+// src/theme/blocks/_grid.scss
+.block.gridBlock .four .slate:not(.inner) {
+  padding: 2.5rem;
+  padding-top: 4rem;
+  backdrop-filter: blur(20px) saturate(110%);
+  box-shadow:
+    0 8px 32px 0 rgb(31 135 125 / 10%),
+    inset 0 0 0 1px rgb(255 255 255 / 10%);
 }
+```
 
-#sidebar {
- .color-swatch-widget {
-      .buttons button.teal {
-        background: linear-gradient(135deg, var(--secondary-color) 0%, #fff 100%);
-      }
-    }
+```scss
+// src/theme/blocks/_teaser.scss
+.block.teaser .card .card-inner .card-summary {
+  padding: $spacing-large;
 }
 ```
 
-### Step 3: Configure Block Themes
+The teaser rule uses `$spacing-large`, one of VLT's SCSS variables.
+Those are in scope for your stylesheets because {file}`_main.scss` is compiled after VLT's variables and mixins, so you can reuse the theme's spacing scale, breakpoints, and typography mixins instead of inventing new values.
+
+(charging-bay-label)=
+
+### Step 5: Configure Block Themes
 
-In `src/config/blocks.ts`, define block themes:
+Block themes are the palettes an editor can choose between on any block. The Robotarium gets two: the plain default, and **Charging Bay**, a soft teal wash for sections that should feel like the lit alcove where the robots dock.
+
+In `src/config/blocks.ts`, define them:
 
 ```typescript
 import type { ConfigType } from '@plone/registry';
 
 export default function install(config: ConfigType) {
   // Block palettes
-    config.blocks.themes = [
+  config.blocks.themes = [
     {
       style: {
         '--theme-color': 'white',
@@ -227,18 +281,60 @@ export default function install(config: ConfigType) {
         '--theme-foreground-color': 'black',
         '--theme-low-contrast-foreground-color': '#555555',
       },
-      name: 'teal',
-      label: 'Teal',
+      name: 'charging-bay',
+      label: 'Charging Bay',
     },
   ];
 
+  // Re-point the Grid block at the new palettes. See below.
+  config.blocks.blocksConfig.gridBlock.themes = config.blocks.themes;
+
+  return config;
+}
+```
+
+```{note}
+The Grid block is the only block in VLT—or in any of the recommended add-ons—that keeps its own copy of the palettes, so this is the only place the extra line is needed.
+```
+
+### Step 6: Keep the Layout Settings in Sync
+
+Widening the container in SCSS is only half the change.
+VLT also reads the container width from configuration, in {file}`src/config/settings.ts`.
+Add the `layout` block to the file Cookieplone generated—do not replace it, or you will drop your language settings:
+
+```typescript
+import type { ConfigType } from '@plone/registry';
+
+export default function install(config: ConfigType) {
+  // Language settings (generated — keep these)
+  config.settings.isMultilingual = false;
+  config.settings.supportedLanguages = ['en'];
+  config.settings.defaultLanguage = 'en';
+
+  // Added in this step
+  config.settings.layout = {
+    ...config.settings.layout,
+    defaultContainerWidth: 1120,
+  };
+
   return config;
 }
 ```
 
-### Step 4: Main Index Configuration
+This value is not used for layout—the CSS custom property does that. It is used to compute the `sizes` attribute of responsive images in teasers and listings, which tells the browser how wide an image will actually be so it can pick the right scale to download.
 
-In `src/index.ts`:
+If the two disagree, nothing breaks visibly, but the browser makes its choice from the wrong number and downloads scales that are too small, so images look soft.
+Whenever you change `$default-container-width`, change `defaultContainerWidth` to match.
+
+```{note}
+`config.settings.layout` also carries `tabletBreakpoint`, used in the same calculation.
+Keep it in sync with `$tablet-breakpoint` for the same reason.
+```
+
+### Step 7: Main Index Configuration
+
+The generated {file}`src/index.ts` already calls `installSettings`. Add the two lines that wire up your block configuration:
 
 ```typescript
 import type { ConfigType } from '@plone/registry';
@@ -254,10 +350,32 @@ function applyConfig(config: ConfigType) {
 export default applyConfig;
 ```
 
-### Step 5: Import SCSS Files
+### Step 8: Import Your Stylesheets
 
-In `src/theme/_main.scss`:
+{file}`_main.scss` is the entry point Volto injects after all of VLT's styles. Import your partials there, in the order you want them applied:
 
 ```scss
-@import './site';
-```
\ No newline at end of file
+// src/theme/_main.scss
+// ... your @font-face rules, :root tokens, and site-wide rules above ...
+
+@import './blocks/button';
+@import './blocks/grid';
+@import './blocks/slider';
+@import './blocks/teaser';
+```
+
+{file}`_variables.scss` needs no import. Volto picks it up on its own and injects it ahead of VLT's variables.
+
+## Checkpoint
+
+Restart the frontend and confirm the following before moving on:
+
+- The site renders in your custom font, and the header and footer show their gradients.
+- Links use `--link-foreground-color` rather than the surrounding text color.
+- Opening a page in edit mode and selecting a block shows **Default** and **Charging Bay** in the block's color theme selector.
+
+## Further Reading
+
+- [Color system](https://volto-light-theme.readthedocs.io/conceptual-guides/color-system.html)
+- [Colors reference](https://volto-light-theme.readthedocs.io/reference/colors.html)
+- [Layout](https://volto-light-theme.readthedocs.io/conceptual-guides/layout.html)
diff --git a/docs/customizing-volto-light-theme/index.md b/docs/customizing-volto-light-theme/index.md
index 04260b9a7..5e97d67cd 100644
--- a/docs/customizing-volto-light-theme/index.md
+++ b/docs/customizing-volto-light-theme/index.md
@@ -20,6 +20,8 @@ The goal of this training is to guide developers in understanding and effectivel
 
 Participants will explore essential aspects of Volto Light Theme such as setting up theme providers, customizing styles, and understanding how Volto's theming system functions. The training also covers advanced tips, best practices, and lesser-known features to extend Volto Light Theme and create more tailored solutions.
 
+The chapters build one site together: **the Robotarium**, a workshop that lends robots the way a library lends books. Each feature is introduced where that site needs it, so the theming concepts arrive attached to a concrete problem rather than in the abstract.
+
 This training is best suited for developers who have prior experience with Volto and want to deepen their theming knowledge.
 
 ```{toctree}
diff --git a/docs/customizing-volto-light-theme/question-answer.md b/docs/customizing-volto-light-theme/question-answer.md
index 1c711fda9..06aa38f6a 100644
--- a/docs/customizing-volto-light-theme/question-answer.md
+++ b/docs/customizing-volto-light-theme/question-answer.md
@@ -7,4 +7,88 @@ myst:
     "keywords": "Plone, Volto, Training, Volto Light Theme"
 ---
 
-# Questions and answers
+# Questions and Answers
+
+This chapter collects the questions that come up most often while working through the training, together with the answers you would otherwise have to dig out of the source.
+
+## Setup
+
+### My styles do not appear at all
+
+Check three things, in order:
+
+1. VLT is declared as the `theme`, not only as an add-on. It is both, and the `addons` entry alone does not apply the theme.
+2. Your project add-on is applied after VLT. VLT must be the last entry in your add-on's `addons` list.
+3. Your stylesheet is reachable from {file}`src/theme/_main.scss`. Volto only picks up that exact filename.
+
+Restart the frontend after any of these. Adding files is not picked up by hot reload.
+
+### Why is `theme/_main.scss` special?
+
+Volto scans every add-on for {file}`theme/_variables.scss` and {file}`theme/_main.scss` and injects whichever it finds into two fixed points in the theme's stylesheet—variables before VLT's own, main after all of VLT's styles. The filenames are the contract; renaming them silently disables the hook.
+
+### Where do I override `$spacing-large` or a breakpoint?
+
+In {file}`src/theme/_variables.scss`. VLT declares its SCSS variables with `!default`, and that file is injected first, so your value wins. Assigning them from {file}`_main.scss` has no effect, because VLT's stylesheets have already been compiled by then.
+
+## Styling
+
+### Should I use `--theme-color` or `--primary-color`?
+
+`--theme-color` and its companions are set per block by the selected block theme, and change as the editor picks a different one. The `--primary-color` family is site-wide. Inside a block, read the theme properties so the block adapts to whichever palette it is given; outside blocks, read the site-wide ones.
+
+### My links are the same color as the surrounding text
+
+That is the default. Links inherit `--theme-foreground-color` so they stay legible against any block theme. Define `--link-foreground-color` in your project to give them a color of their own.
+
+### Where do the `next--is--...` classes in VLT's CSS come from?
+
+From `config.settings.styleClassNameExtenders`. They describe each block's relationship to its neighbors—same type, same background, first or last of a run—so that vertical spacing can be expressed in CSS instead of in the components. The full list is in the first chapter.
+
+## Blocks and widgets
+
+### My alignment or width buttons appear but do nothing
+
+The field name is almost certainly missing its `:noprefix` suffix. `align` and `align:noprefix` are two different fields, and only the second matches the style definition that injects `--block-alignment`. The same applies to `blockWidth:noprefix` and `size:noprefix`.
+
+### What does `:noprefix` actually do?
+
+It stops the StyleWrapper prefixing the generated CSS class with the field name. A field `align` with value `center` produces `has--align--center`; `align:noprefix` produces `center`. VLT registers its style definitions under the suffixed names, so the suffix is also what makes the lookup match.
+
+### Can I reuse a Volto block id for my own block?
+
+Avoid it. VLT restricts some core blocks—the legacy `hero` among them—and registering under the same key overwrites a core block rather than adding yours, which makes the result depend on add-on ordering. Give project blocks their own key.
+
+### How do I add the background color control to a third-party block?
+
+Register VLT's `defaultStylingSchema` as the block's `schemaEnhancer`, composing it with any enhancer the block already has:
+
+```typescript
+config.blocks.blocksConfig.<blockId> = {
+  ...config.blocks.blocksConfig.<blockId>,
+  schemaEnhancer: composeSchema(
+    config.blocks.blocksConfig.<blockId>.schemaEnhancer,
+    defaultStylingSchema,
+  ),
+};
+```
+
+## Components
+
+### Should I shadow VLT's header, or swap it?
+
+Swap it. VLT 8 resolves its structural components through the registry, so registering your own and naming it in `config.settings.vlt.components` replaces it without shadowing. Shadowing still works, but it binds you to an internal module path and hides which component is actually active.
+
+### Slot or component swap?
+
+Use a slot to add something to the layout. Swap a structural component to replace one. Slots are additive and several components can occupy one; a swap substitutes a single named role.
+
+## Block Model v3
+
+### Should I enable it?
+
+Only once every block in your registry is v3-compatible. Block repositories advertise this with a "BMv3 ready" banner. A block left on the older model still renders, but it will not share the container structure of the surrounding page, and the difference shows.
+
+### Do I need to set categories on VLT's blocks?
+
+No. VLT already assigns them to the blocks it has migrated. Set `category` on your own blocks, and remember that a category only means something if your stylesheets act on the `category-*` class it produces.
diff --git a/styles/config/vocabularies/Plone/accept.txt b/styles/config/vocabularies/Plone/accept.txt
index 52aeee0e9..c3984f3f6 100644
--- a/styles/config/vocabularies/Plone/accept.txt
+++ b/styles/config/vocabularies/Plone/accept.txt
@@ -220,6 +220,7 @@ viewlet
 Virtualbox
 virtualenv
 VMWare
+VLT
 Volto
 von
 VSCode

From fd8a7bfd8482b8c9ac860497f885960d6d605329 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dante=20=C3=81lvarez?=
 <89805481+danalvrz@users.noreply.github.com>
Date: Fri, 18 Sep 2026 15:23:38 +0200
Subject: [PATCH 10/10] improve docs

---
 .../advanced-components-bm3.md                | 495 +++++++--------
 .../block-development-widgets.md              | 588 +++++++++++-------
 .../customizing-volto-light-theme/concepts.md | 444 ++++++-------
 .../design-system-implementation.md           | 193 +++---
 docs/customizing-volto-light-theme/index.md   |  15 +-
 .../question-answer.md                        |  73 ++-
 styles/config/vocabularies/Plone/accept.txt   |   5 +
 7 files changed, 998 insertions(+), 815 deletions(-)

diff --git a/docs/customizing-volto-light-theme/advanced-components-bm3.md b/docs/customizing-volto-light-theme/advanced-components-bm3.md
index 87ef67539..6558137e1 100644
--- a/docs/customizing-volto-light-theme/advanced-components-bm3.md
+++ b/docs/customizing-volto-light-theme/advanced-components-bm3.md
@@ -1,13 +1,13 @@
 ---
 myst:
   html_meta:
-    "description": "Advanced Components, Site Customization & Block Model v3"
-    "property=og:description": "Advanced Components, Site Customization & Block Model v3"
-    "property=og:title": "Advanced Components, Site Customization & Block Model v3"
+    "description": "Advanced Components, Slots & Block Model v3"
+    "property=og:description": "Advanced Components, Slots & Block Model v3"
+    "property=og:title": "Advanced Components, Slots & Block Model v3"
     "keywords": "Plone, Volto, Training, Volto Light Theme, Integrate, block"
 ---
 
-# Advanced Components, Site Customization & Block Model v3
+# Advanced Components, Slots & Block Model v3
 
 ## Understanding the Card Primitive
 
@@ -37,18 +37,23 @@ A card becomes a link when you give it either an `item` or an `href`. The two ar
 <Card href="/workshop/hours">...</Card>  // for arbitrary destinations
 ```
 
-Passing `item` lets the underlying `UniversalLink` inspect the content type, so a File links to its download URL and an Image to its view, rather than to the object's default page.
-Passing `href={item['@id']}` skips that, and those types end up linking to the wrong place.
+The link wraps the title inside the summary, and a CSS overlay stretches its clickable area across the whole card.
+
+Passing `item` lets the underlying link inspect the content type.
+For visitors who are not logged in, a File links to its download URL, and a Link item links to its target URL.
+Passing `href={item['@id']}` skips that, and those items link to their own page instead.
 Use `href` when you genuinely have only a URL.
 
 Pass `null` to make the card non-interactive, which is what listing templates do in edit mode.
 
 ### Card Variations
 
-- **Vertical layout** (default): Image on top
-- **Horizontal layout**: Image on left or right
-- **Contained**: With background color from theme
-- **Listing**: Image displayed on left with specific size (controlled by `--card-listing-image-size`, default 220px)
+The layout of a card depends on where it is rendered:
+
+- **Vertical** (default): the image is on top.
+- **Horizontal**: the image is on the left or on the right, when the surrounding block is aligned left or right, as a Teaser block can be.
+- **Contained**: inside a container block, such as a Grid, the summary gets side padding, and the card takes its background color from the current theme.
+- **Listing**: inside a `.card-listing` wrapper, the image is on the left, with a fixed width set by `--card-listing-image-size`, 220px by default.
 
 ### Card.Image Slot
 
@@ -72,6 +77,7 @@ A `src` prop works too, for an image that is not a content object. To control ho
 Recommended structure using VLT's Summary component:
 
 ```tsx
+import config from '@plone/volto/registry';
 import DefaultSummary from '@kitconcept/volto-light-theme/components/Summary/DefaultSummary';
 
 const Summary = config.getComponent({
@@ -85,18 +91,19 @@ const Summary = config.getComponent({
 ```
 
 `Card` generates an id for the card's accessible name and builds a link component for the item, then passes both down to its slots as the `a11yLabelId` and `LinkToItem` props.
-Slots forward them to their children, so a Summary rendered inside `Card.Summary` receives them without you wiring anything up.
+`Card.Summary` forwards them to its children, so a Summary rendered inside it receives them without you wiring anything up.
 Using them is what gives the card an accessible name and a real link—see the next section.
 
 ## Creating Custom Summary Components
 
-The Summary component displays content metadata in listings, teasers, and cards. VLT includes built-in implementations:
+The Summary component displays content metadata in listings, teasers, and cards.
+VLT includes these implementations, and registers all but the first for their content types:
 
-- `DefaultSummary`: Kicker, title, and description
-- `NewsItemSummary`: Publication date, kicker, title, description
-- `EventSummary`: Start/end date, kicker, title, description
-- `FileSummary`: File size and type
-- `PersonSummary`: Contact details for the Person content type
+- `DefaultSummary`: the kicker, title, and description. It is the fallback for all other types.
+- `NewsItemSummary`, for News Items: the publication date and the kicker, then the title and description.
+- `EventSummary`, for Events: the start and end dates and the kicker, then the title and description.
+- `FileSummary`, for Files: the file size, file type, and kicker, then the title and description.
+- `PersonSummary`, for the Person type: the kicker, title, and description, plus the email address, phone number, and room.
 
 ### The Summary Contract
 
@@ -145,29 +152,31 @@ A Summary that omits them renders a card that looks right but cannot be navigate
 
 The Robotarium lends robots, so it needs a content type for them. Create it through the Plone UI:
 
-1. Go to http://localhost:3000/controlpanel/dexterity-types
-2. Click "Add New Content Type"
-3. Fill in:
-   - **Type Name**: Robot
+1. Go to http://localhost:3000/controlpanel/dexterity-types.
+2. Select the **Add** button in the toolbar.
+3. In the **Add new content type** form, fill in:
+   - **Title**: Robot
    - **Description**: A robot available for booking
-4. Click "Add"
-5. In the "Behaviors" tab, enable:
-   - **Kicker field**, which adds `head_title`. We will use it to store the robot's charge level.
-   - **Preview Image**, so robots can show a photo in listings.
-   - Any other behaviors you want, such as Dublin Core metadata.
-6. Click "Save"
+4. Select **Save**.
+5. Select **Robot** in the list of content types.
+6. In the **Behaviors** tab, enable:
+   - **Kicker field**, which adds a field named `head_title`. The Robotarium uses it to store the robot's charge level.
+   - **Preview Image**, so that robots can show a photo in listings.
+   - Any other behaviors you want.
+7. Select **Save**.
 
 ```{note}
-The form asks only for a name and a description. Plone derives the type's id from the name by normalizing it, so **Robot** becomes `robot`, and a name like **Charging Station** would become `charging_station`.
+The form asks only for a title and a description. Plone derives the type's id from the title by normalizing it, so **Robot** becomes `robot`, and a title like **Charging Station** would become `charging_station`.
 
-That id is what the REST API returns as the content's `@type`, and it is the value you register components against later in this chapter. It is worth confirming rather than assuming: open a robot you created and check the `@type` in `http://localhost:8080/Plone/<path>`, or look at the URL of the type you just added in the control panel.
+That id is what the REST API returns as the content's `@type`, and it is the value you register components against later in this chapter.
+It is worth confirming rather than assuming: open http://localhost:3000/++api++/ followed by the path of a robot you created, and check its `@type`.
 
 Plone's built-in types predate this rule and keep their historical ids, which is why VLT registers its news summary against `News Item`, with a space and capitals, rather than `news_item`.
 ```
 
 ### Step 2: Create a Custom Summary Component
 
-Create `src/components/Summary/RobotSummary.tsx`:
+Create {file}`src/components/Summary/RobotSummary.tsx`:
 
 ```tsx
 import * as React from 'react';
@@ -218,13 +227,16 @@ export default RobotSummary;
 
 The `HeadingTag` default is `'div'` rather than a fixed heading level. The caller decides the level, because the right one depends on where the listing sits in the page's heading outline.
 
-**Note**: We are reusing the kicker (`head_title`) to hold the charge level, so that the example needs no new field. A real Robotarium would add a proper numeric field to the Robot type instead, and reserve the kicker for what it is meant for: a line of text above the title.
+```{note}
+The example reuses the kicker (`head_title`) to hold the charge level, so that it needs no new field.
+A real Robotarium would add a proper numeric field to the Robot type instead, and reserve the kicker for what it is meant for: a line of text above the title.
+```
 
 ### Step 3: Add Styles for the Robot Summary
 
 The charge is the one thing VLT has no styling for, so it is the one thing this partial has to describe: a labelled row above a slim track whose fill is as wide as the charge.
 
-Create `src/theme/_robotSummary.scss`:
+Create {file}`src/theme/_robotSummary.scss`:
 
 ```scss
 .robot-charge {
@@ -270,22 +282,21 @@ Create `src/theme/_robotSummary.scss`:
 
 Three decisions here are worth carrying to your own work.
 
-**Nothing is scoped to the listing.** A Summary is rendered in listings, in teasers, and in bare cards, and the same component should look the same in all of them. Scoping these rules to the fleet listing—`.robots .card .card-summary .robot-charge`—would style the listing and leave the same robot in a teaser looking like a different component. Selecting on what the Summary itself renders keeps the contexts in step.
+**Nothing is scoped to the listing.** A Summary is rendered in listings, in teasers, and in bare cards, and the same component should look the same in all of them. Scoping these rules to the fleet listing, with a selector such as `.robots .card .card-summary .robot-charge`, would style the listing and leave the same robot in a teaser looking like a different component. Selecting on what the Summary itself renders keeps the contexts in step.
 
-Import in `src/theme/_main.scss`:
+**The colors come from tokens.** The track mixes the theme's foreground color with transparency, so it stays visible on any block theme, and the fill follows `--accent-color`, so it changes with the design.
+
+**The typography comes from VLT.** The label uses VLT's `headtitle2()` mixin, one of the theme's text styles for small labels, instead of a font size of its own.
+
+Import the partial at the end of {file}`src/theme/_main.scss`:
 
 ```scss
-@import './blocks/button';
-@import './blocks/cover';
-@import './blocks/grid';
-@import './blocks/slider';
-@import './blocks/teaser';
 @import './robotSummary';
 ```
 
 ### Step 4: Register the Summary Component
 
-In `src/config/settings.ts`:
+In {file}`src/config/settings.ts`:
 
 ```typescript
 import RobotSummary from '../components/Summary/RobotSummary';
@@ -305,31 +316,36 @@ export default function install(config: ConfigType) {
 
 ### Step 5: Test the Robot Summary
 
-1. Add a Robot to your site, for example **ARM-7 Bench Arm**
-2. Fill in the title, a short description, and the kicker with a plain number such as `87`
-3. Add the robot to a Listing or Teaser block
-4. `RobotSummary` renders the title, description, and a charge level of 87%
+1. Add a Robot to your site, for example **ARM-7 Bench Arm**.
+2. Fill in the title, a short description, and the kicker with a plain number such as `87`.
+3. Add the robot to a Listing or Teaser block.
+4. `RobotSummary` renders the title, the description, and a charge level of 87%.
 
 ## Creating Custom Listing Variations with Card Actions
 
-Listing variations customize content display in Listing blocks. Let's build a `RobotsTemplate` that presents the fleet and uses the Card.Actions slot for a booking button.
+Listing variations customize how a Listing block displays its content. This section builds a `RobotsTemplate` that presents the fleet and uses the Card.Actions slot for a booking button.
 
 ### Card.Actions Slot
 
 ```{important}
-`Card.Actions` only renders what a template puts in it, and **none of VLT's built-in listing variations put anything there**. Registering an `Actions` component is not enough on its own: List, List with images, Grid, and the Teaser block all ignore the slot, so a card rendered by any of them shows no actions.
+`Card.Actions` only renders what a template puts in it, and **none of VLT's built-in listing variations put anything there**.
+Registering an `Actions` component is not enough on its own: the List, List with images, and Grid variations, and the Teaser block, all ignore the slot, so a card rendered by any of them shows no actions.
 
 That is why the fleet listing below needs its own template. If you register an Actions component and see nothing, check which variation the listing is using before suspecting the registration.
 ```
 
 The Card.Actions slot provides interactive elements beyond the main card link:
+
 - "Book this unit" for a robot that is available
-- "Download spec sheet" for its documentation
+- "Download specifications" for its documentation
 - "Reserve a slot" for a robot that is currently out
 
+The card's link overlay covers the whole card, so the actions have to sit above it. Otherwise, selecting an action would open the card's link instead.
+The stylesheet in Step 5 takes care of that.
+
 ### Step 1: Create RobotActions Component
 
-Create `src/components/Actions/RobotActions.tsx`:
+Create {file}`src/components/Actions/RobotActions.tsx`:
 
 ```tsx
 const RobotActions = ({ item }) => {
@@ -347,7 +363,7 @@ The button carries `type="button"` so it does not submit a surrounding form, and
 
 ### Step 2: Register RobotActions
 
-Update `src/config/settings.ts`:
+Update {file}`src/config/settings.ts`:
 
 ```typescript
 import RobotActions from '../components/Actions/RobotActions';
@@ -368,7 +384,7 @@ export default function install(config: ConfigType) {
 
 ### Step 3: Create RobotsTemplate Listing Variation
 
-Create `src/components/blocks/Listing/RobotsTemplate.tsx`:
+Create {file}`src/components/blocks/Listing/RobotsTemplate.tsx`:
 
 ```tsx
 import React from 'react';
@@ -422,16 +438,14 @@ const RobotsTemplate = ({ items, linkTitle, linkHref, isEditMode }) => {
               key={item['@id']}
             >
               <Card item={showLink ? item : null}>
-                {(item.image_field !== '' || placeholderSrc) && (
-                  <Card.Image
-                    className="item-image"
-                    item={item}
-                    showPlaceholderImage={true}
-                    placeholderSrc={placeholderSrc}
-                    imageComponent={PreviewImageComponent}
-                    sizes={`(max-width: ${config.settings.layout.tabletBreakpoint}px) 100vw, ${Math.trunc(config.settings.layout.defaultContainerWidth / 2)}px`}
-                  />
-                )}
+                <Card.Image
+                  className="item-image"
+                  item={item}
+                  showPlaceholderImage={true}
+                  placeholderSrc={placeholderSrc}
+                  imageComponent={PreviewImageComponent}
+                  sizes={`(max-width: ${config.settings.layout.tabletBreakpoint}px) 100vw, ${Math.trunc(config.settings.layout.defaultContainerWidth / 2)}px`}
+                />
                 <Card.Summary>
                   <Summary item={item} />
                 </Card.Summary>
@@ -460,25 +474,54 @@ export default RobotsTemplate;
 ```
 
 **Key Features:**
-- Uses `config.getComponent()` to fetch registered Summary/Actions components by content type
-- `showLink` ensures cards are only clickable when appropriate
-- `isEditMode` disables navigation during editing
-- Dynamically renders Actions only for content types that have them registered
-- Renders a `<ul>` of `<li>` elements, matching VLT's own listing templates, so assistive technology announces the item count
-- Passes `item` to `Card` rather than a bare URL, so content types with their own link behavior, such as File, resolve correctly
-- Passes `sizes` and the placeholder props to `Card.Image`, exactly as VLT's own variations do
+
+- Uses `config.getComponent()` to fetch the Summary and Actions components registered for each content type
+- Renders actions only for content types that have an Actions component registered
+- Always renders the image slot, so a robot without a photo shows a placeholder, and every card in a row has the same shape
+- Passes `null` to `Card` in edit mode, or when the Summary sets `hideLink`, so that the card is not a link there
+- Passes `item` to `Card` rather than a bare URL, so that content types with their own link behavior, such as File, resolve correctly
+- Renders a `<ul>` of `<li>` elements, matching VLT's own listing templates, so assistive technology announces the number of items
 
 ```{important}
 Write a variation by starting from the VLT variation closest to what you want—here that is `GridTemplate`, since the fleet is a two-column card grid—and change only what has to change.
 
-The two additions above are a good illustration of why. `sizes` tells the browser how wide the image will actually render, so that it downloads the right scale; omit it and the cards look soft for no visible reason. `showPlaceholderImage` and `placeholderSrc` keep the grid from collapsing on an item that has no image. Neither is obvious from the outside, and both come for free by following the shape of the template you are adapting.
+The image props illustrate why. `sizes` tells the browser how wide the image will actually render, so that it downloads the right scale; omit it and the cards look soft for no visible reason. It is not obvious from the outside, and it comes for free by following the shape of the template you are adapting.
+
+The same applies to the stylesheet in Step 5.
+```
+
+The fleet deviates from `GridTemplate` in one deliberate place.
+`GridTemplate` renders `Card.Image` only when an item has an image, or when a placeholder is registered for its content type.
+`RobotsTemplate` always renders it, with `showPlaceholderImage`, so a robot without a photo shows Volto's default placeholder image instead of an empty space.
+
+To show a robot-specific placeholder instead, add an image to your add-on, for example {file}`src/assets/robot-placeholder.svg`, and register it for the `robot` type in {file}`src/config/settings.ts`:
+
+```typescript
+import robotPlaceholderImage from '../assets/robot-placeholder.svg';
+
+export default function install(config: ConfigType) {
+  // ... previous configuration ...
 
-The same applies to the stylesheet in the next step.
+  config.settings.placeholderImages = {
+    ...config.settings.placeholderImages,
+    robot: robotPlaceholderImage,
+  };
+
+  return config;
+}
+```
+
+The key is the content type id, the same one you registered the Summary and Actions components against.
+VLT's Teaser block and its own listing variations read the same setting, so a robot without a photo shows the same placeholder there.
+
+```{note}
+Do not put the placeholder in a folder named {file}`icons`.
+Volto loads SVG files from {file}`icons` folders as inline icons rather than as image files, so they cannot be used as the source of an image.
 ```
 
 ### Step 4: Register RobotsTemplate
 
-Update `src/config/blocks.ts`:
+Update {file}`src/config/blocks.ts`:
 
 ```typescript
 import RobotsTemplate from '../components/blocks/Listing/RobotsTemplate';
@@ -500,18 +543,18 @@ export default function install(config: ConfigType) {
 }
 ```
 
+The Listing block adds the id of the selected variation to its classes, so the block renders as `.block.listing.robots`, which the stylesheet in the next step targets.
+
 ### Step 5: Add Styles
 
-The fleet is a two-column card grid, which is what VLT's own `grid` variation already is—so the stylesheet is that variation's rules, repeated for `robots`, plus the two things the grid variation has no equivalent for: the card surface, and the actions row.
+The fleet is a two-column card grid, which is what VLT's own `grid` variation already is.
+The stylesheet repeats that variation's rules for `robots`, and adds the two things the grid variation has no equivalent for: the card surface, and the actions row.
 
-Create `src/theme/blocks/_listing.scss`:
+Create {file}`src/theme/blocks/_listing.scss`:
 
 ```scss
-// The Robot Fleet variation is a two-column card grid, which is exactly what
-// VLT's own `grid` variation already is. These rules mirror `.block.listing.grid`
-// in VLT's `theme/blocks/_listing.scss` and `theme/_layout.scss`; the only
-// additions are the card surface and the actions row, which the grid variation
-// has no equivalent for.
+// The rules below mirror `.block.listing.grid` in VLT's
+// `theme/blocks/_listing.scss` and `theme/_layout.scss`.
 
 // VLT constrains most listing variations per item, and the grid variation as a
 // whole. A card grid needs the second treatment, so repeat for `robots` what
@@ -628,10 +671,15 @@ Create `src/theme/blocks/_listing.scss`:
       // The fleet's own addition: the Card.Actions slot, which none of VLT's
       // variations fill.
       .actions-wrapper {
+        // Raise the actions above the card's link overlay, which covers the
+        // whole card, so that the buttons receive clicks. VLT does the same
+        // for additional links inside a card.
+        position: relative;
+        z-index: 1;
         // The last of the stretching boxes: `auto` here is what pins the
         // actions to the bottom of a card that is taller than its content.
         margin-top: auto;
-        padding: $spacing-small $spacing-small 0 $spacing-small;
+        padding: $spacing-medium $spacing-small 0 $spacing-small;
         text-align: right;
 
         .book-unit-button {
@@ -662,67 +710,52 @@ Create `src/theme/blocks/_listing.scss`:
 }
 ```
 
-Import in `src/theme/_main.scss`:
+Import the partial in {file}`src/theme/_main.scss`, next to the other block partials:
 
 ```scss
-@import './blocks/button';
-@import './blocks/cover';
-@import './blocks/grid';
 @import './blocks/listing';
-@import './blocks/slider';
-@import './blocks/teaser';
-@import './robotSummary';
 ```
 
 ### Step 6: Test the Fleet Listing
 
-1. Add a few robots, such as **ARM-7 Bench Arm**, **ROVER-2 Terrain Scout**, **QUAD-4 Walker**, and **DRONE-1 Surveyor**, each with a description, a charge level in the kicker, and an image
-2. Add a Listing block to a page
-3. Select the **Robot Fleet** variation in the block settings
-4. Configure the block to list the Robot content type
-5. Each robot appears with its image, summary, charge level, and a Book button
+1. Add a few robots, such as **ARM-7 Bench Arm**, **ROVER-2 Terrain Scout**, **QUAD-4 Walker**, and **DRONE-1 Surveyor**, each with a description, a charge level in the kicker, and an image.
+2. Add a Listing block to a page.
+3. Select the **Robot Fleet** variation in the block settings.
+4. Configure the block to list the Robot content type.
+5. Each robot appears with its image, summary, charge level, and a Book button, and selecting a Book button does not open the robot's page.
+6. Add a robot without an image. Its card shows the placeholder, and has the same shape as the others.
+
+(light-theme-slots-label)=
 
 ## Working with Slots
 
-VLT provides slots for extending the layout without component shadowing. Let's create a practical example: a sign-up form for **Signal**, the Robotarium's workshop bulletin, in the preFooter slot.
+VLT provides slots for extending the layout without component shadowing. This section adds a practical example: a sign-up form for **Signal**, the Robotarium's workshop bulletin, in the `preFooter` slot.
 
 ### Available Slots
 
-Volto core renders three slots, and VLT's header, footer, and listing add the rest:
-
-| Slot | Where | Arrives with |
-| --- | --- | --- |
-| `aboveApp` | Outermost, around the whole app | `plone-components-css` |
-| `aboveContent` | Above the content view | — |
-| `belowContent` | Below the content view | **`tags` and `relatedItems`** |
-| `aboveHeader` | Above the header | — |
-| `belowHeader` | Below the header | — |
-| `headerTools` | Header, top right | Anontools |
-| `preFooter` | Before the footer | — |
-| `footer` | Main footer area | VLT's footer |
-| `postFooter` | After the footer | — |
-| `footerLinks` | Footer links section | VLT's footer links |
-| `followUs` | Social media section | — |
-| `aboveListingItems` | Inside a Listing block, above the items | — |
-
-```{important}
-Most slots start empty, but `belowContent` does not.
-Volto registers `tags` and `relatedItems` into it by default, so every content view already renders a tag list and a related-items list before you add anything.
-
-Because the last registration wins, and add-on configuration runs after core's, you displace a built-in by re-registering its name with a component that renders nothing:
-
-    config.registerSlotComponent({
-      slot: 'belowContent',
-      name: 'relatedItems',
-      component: () => null,
-    });
-
-Check what a slot already contains before you register into it.
-```
+Volto renders four slots itself, and VLT's header and footer add the others.
+Several of them already contain components when you start:
+
+| Slot | Where it renders | Rendered by | Registered by default |
+| --- | --- | --- | --- |
+| `aboveApp` | Around the whole app | Volto | `plone-components-css`, in the CMS UI only |
+| `aboveContent` | Above the content | Volto | — |
+| `belowContent` | Below the content | Volto | `tags`, `relatedItems` |
+| `aboveListingItems` | Inside a Listing block, above the items | Volto and VLT | — |
+| `aboveHeader` | Above the header | VLT | `Theming`, `StickyMenu` |
+| `belowHeader` | Below the header | VLT | — |
+| `headerTools` | Top right of the header, and in the mobile menu | VLT | `Anontools` |
+| `preFooter` | Top of the footer | VLT | `footerLogos`, `MobileStickyMenu` |
+| `footer` | Main footer area | VLT | `coreFooter`, only with the `kitconcept.footer` behavior |
+| `postFooter` | Bottom of the footer | VLT | `PostFooterFollowUsLogoAndLinks`, `Colophon` |
+| `followUs` | Social media links, inside `postFooter` | VLT | `FollowUs`, from `@plonegovbr/volto-social-media` |
+| `footerLinks` | Footer links, inside `postFooter` | VLT | — |
+
+The `followUs` slot only renders when the site has social media links, and `footerLinks` only when it has footer links.
 
 ### Step 1: Create the Signal Sign-up Component
 
-Create `src/components/SignalSignup/SignalSignup.tsx`:
+Create {file}`src/components/SignalSignup/SignalSignup.tsx`:
 
 ```tsx
 import React, { useState } from 'react';
@@ -769,12 +802,14 @@ export default SignalSignup;
 
 ### Step 2: Add Styles
 
-Create `src/theme/_signalSignup.scss`:
+Create {file}`src/theme/_signalSignup.scss`:
 
 ```scss
-// VLT pads the footer's first child with `#footer > :first-child:not(:empty)`
-// (1,1,0). The sign-up band brings its own padding and its own background, so
-// that padding shows up as a gap in the footer's gradient above it.
+// VLT pads every non-empty container in the footer, with
+// `#footer > .container:not(:empty)`. The sign-up band brings its own padding
+// and its own background, so that padding would show up as a gap in the
+// footer's gradient above it. Both selectors have the same specificity, and
+// this one wins because it loads later.
 #footer > .pre-footer:has(.signal-signup) {
   padding: 0;
 }
@@ -846,22 +881,15 @@ Create `src/theme/_signalSignup.scss`:
 }
 ```
 
-Import in `src/theme/_main.scss`:
+Import the partial at the end of {file}`src/theme/_main.scss`:
 
 ```scss
-@import './blocks/button';
-@import './blocks/cover';
-@import './blocks/grid';
-@import './blocks/listing';
-@import './blocks/slider';
-@import './blocks/teaser';
-@import './robotSummary';
 @import './signalSignup';
 ```
 
 ### Step 3: Register the Component to the Slot
 
-In `src/config/settings.ts`:
+In {file}`src/config/settings.ts`:
 
 ```typescript
 import SignalSignup from '../components/SignalSignup/SignalSignup';
@@ -879,7 +907,9 @@ export default function install(config: ConfigType) {
 }
 ```
 
-The Signal sign-up now appears before the footer on every page, demonstrating how slots let you extend the layout without shadowing core components.
+The Signal sign-up now appears at the top of the footer on every page, after any footer logos, which shows how slots let you extend the layout without shadowing core components.
+
+(light-theme-swap-components-label)=
 
 ## Swapping Structural Components
 
@@ -935,7 +965,7 @@ Both implementations now sit in the registry, and nothing renders differently ye
 config.settings.vlt.components.navigation = 'robotarium';
 ```
 
-That is the whole change. VLT's header resolves the navigation through the registry when it renders, so it picks up your component. Every other role keeps its `vlt` default, and VLT's own navigation stays registered under `vlt`—so reverting is a one-line edit, not a file deletion.
+That is the whole change. VLT's header resolves the navigation through the registry when it renders, so it picks up your component. Every other role keeps its `vlt` default, and VLT's own navigation stays registered under `vlt`, so reverting is a one-line edit, not a file deletion.
 
 The same two steps swap any of the nine roles.
 
@@ -948,52 +978,17 @@ The same two steps swap any of the nine roles.
 - **Typed.** The keys of `config.settings.vlt.components` are a fixed set, so a misspelled role is a compile error rather than a silent no-op.
 
 ```{note}
-Your add-on must be applied after `@kitconcept/volto-light-theme` so that `config.settings.vlt` exists when you assign to it.
-Keeping VLT last in your project add-on's `addons` list, as set up in the first chapter, is enough.
+Your add-on's configuration must run after VLT's, so that `config.settings.vlt` exists when you assign to it.
+It does, because VLT is listed in your add-on's `addons`, and Volto applies the add-ons that an add-on declares before the add-on itself.
 ```
 
-## Site Customization Behaviors
-
-VLT provides backend behaviors for site customization that you activated earlier. These behaviors enable fields for customizing the site without code changes.
-
-### Header Customization Options
-
-Through the Plone UI, you can customize:
-- **Site logo**: Main logo in the top left
-- **Complementary logo**: Second logo on the right side
-- **Fat menu**: Enabled by default, can be disabled
-- **Intranet header**: Alternative header for intranet sites
-- **Site flag**: The colored pill at the top left of the header
-- **Actions**: Links at the top right
-
-### Theme Customization Options
-
-- Navigation text color
-- Fat menu and breadcrumbs text color
-- Fat menu background color
-- Footer font color
-- Footer background color
-
-### Footer Customization Options
-
-- **Footer links**: Additional links with title, URL, and new tab option
-- **Footer logos**: List of logos with links and customizable size (small/large) and container width (default/layout)
-- **Footer colophon text**: Customizable last line of footer
+(light-theme-block-model-v3-label)=
 
 ## Block Model v3 (opt-in)
 
-```{note}
-Block Model v3 is a beta feature. It's recommended to only use it when all blocks in your registry are v3-compatible (indicated by banner in block's GitHub repository).
-```
-
-Block Model v3 introduces a unified container architecture that ensures consistent styling and spacing between View and Edit modes. This eliminates the previous issues where Edit mode appeared different from View mode.
-
-### Key Benefits
-
-- Consistent rendering across View and Edit modes
-- Simplified CSS with standardized container structure
-- Improved spacing control through block categories
-- Reduced maintenance overhead
+Block Model v3 gives every block the same two containers in view mode and in edit mode, so a block looks the same while you edit it as it does on the published page.
+VLT 8 ships it as an opt-in.
+The Robotarium keeps the default, Block Model v2, and this section explains what changes when you switch.
 
 (bm3-two-container-label)=
 
@@ -1020,23 +1015,16 @@ Every block in Block Model v3 follows this structure:
 └────────────────────────────────────────────────────────────┘
 ```
 
-**Main/Outer Container:**
-- Spans the full layout width
-- Handles background colors and theme variables
-- Uses padding (not margin) for vertical spacing
-- CSS Classes: `.block.${type}.category-${category}`
-
-**Secondary/Inner Container:**
-- Controls content width constraints
-- Provides consistent inter-block spacing
-- Supports content alignment through CSS Grid
-- CSS Class: `.block-inner-container`
+The outer container uses padding rather than margin for vertical spacing, so that its background has no gaps.
+In edit mode, VLT renders the same two containers, and adds the editing controls after the inner container.
 
 ### Enable Block Model v3
 
-VLT ships with `config.settings.blockModel = 2` and copies that value onto each block it has migrated. Opting in means setting the flag and re-applying it to those blocks, because they read the value at the time VLT was configured—which is before your add-on runs.
+VLT sets `config.settings.blockModel = 2`, and copies that value to each block it has migrated: `slate`, `title`, `gridBlock`, and the Button block, `__button`.
+Those blocks keep the value they had when VLT's configuration ran, which is before your add-on runs.
+To switch, set the flag, and copy it to those blocks again.
 
-In your project's `src/config/settings.ts`:
+In your project's {file}`src/config/settings.ts`:
 
 ```typescript
 export default function install(config: ConfigType) {
@@ -1045,9 +1033,12 @@ export default function install(config: ConfigType) {
   // Enable Block Model v3 globally
   config.settings.blockModel = 3;
 
-  // Re-apply it to the blocks VLT has migrated
-  for (const type of ['slate', 'title', '__button']) {
-    config.blocks.blocksConfig[type].blockModel = config.settings.blockModel;
+  // Re-apply it to the blocks VLT has migrated.
+  // The Button block only exists if its add-on is installed.
+  for (const type of ['slate', 'title', 'gridBlock', '__button']) {
+    if (config.blocks.blocksConfig[type]) {
+      config.blocks.blocksConfig[type].blockModel = config.settings.blockModel;
+    }
   }
 
   return config;
@@ -1055,87 +1046,102 @@ export default function install(config: ConfigType) {
 ```
 
 ```{important}
-Check each block's repository for the "BMv3 ready" banner before you flip it.
+A block that stays on v2 still renders, but without the two containers, so it can look different from its neighbors.
+Enable v3 only when every block your site uses supports it.
+Block repositories that support it show a "BMv3 ready" badge.
 ```
 
+(light-theme-block-categories-label)=
+
 ### Block Categories
 
-Block categories determine spacing relationships between adjacent blocks, through the `category-${category}` class on the outer container. They are set at `config.blocks.blocksConfig.[$type].category`.
+Under v3, VLT's stylesheet sets the width of a block's inner container, and the space before the next block, according to the block's category.
+The category is set at `config.blocks.blocksConfig[type].category`, and it becomes a `category-${category}` class on the outer container.
+Vertical spacing between blocks comes from the **upper** block: its content sits flush with the top of its container, and the bottom padding creates the space before the next block.
 
 VLT already assigns categories to the blocks it has migrated, so you do not need to repeat them:
 
-| Category | Blocks | Spacing behavior |
-| --- | --- | --- |
-| `inline` | `slate` | Flows as body text |
-| `title` | `title` | Opens a section |
-| `action` | `__button` | A call to action |
-| `cards` | `gridBlock` | Self-contained visual units |
+| Category | Assigned to | Width of the inner container | Spacing adjustments, by the category of the neighboring block |
+| --- | --- | --- | --- |
+| `inline` | `slate` | narrow | no space before `separator`, more space before `action` or `heading` |
+| `title` | `title` | default | no top padding on a `cards` block that follows |
+| `action` | `__button` | the width chosen for the block | no space before `separator`, more space before `cards` or `inline` |
+| `cards` | `gridBlock` | default | more space before `action` or `inline` |
+
+VLT's stylesheet also has rules for a few categories that no block in VLT or in the recommended add-ons assigns yet, such as `heading` and `separator`.
 
-Your own blocks need a category too, and the useful instinct is to reach for one of these four before inventing a fifth. The Cover block renders a self-contained visual unit with its own background, which is what `cards` already describes, so it can reuse it.
+Your own blocks can have a category too.
+Reuse one of the four only if both its width rule and its spacing fit the block.
+The Cover block is a self-contained unit, like the cards in a Grid, but `cards` fixes the inner container at the default width.
+Under v3, that rule is more specific than the Cover's own `max-width`, so the Block Width control would stop working.
 
-These two lines go in {file}`src/config/blocks.ts`, **after** the Cover registration from the previous chapter. They are worth adding even with the flag left at `2`—`blockModel` simply picks up whatever `config.settings.blockModel` currently holds:
+When none of the categories fits, add your own.
+Name it for the family of blocks it describes rather than for the block that prompted it, and give it rules, because a category only means something if your stylesheets act on the `category-*` class it produces.
+The Robotarium adds a `showcase` category, for full-width sections that bring their own background and padding, such as the Cover.
+
+Add these two lines to {file}`src/config/blocks.ts`, after the Cover registration from the previous chapter:
 
 ```typescript
-config.blocks.blocksConfig.cover.category = 'cards';
+config.blocks.blocksConfig.cover.category = 'showcase';
 config.blocks.blocksConfig.cover.blockModel = config.settings.blockModel;
 ```
 
+They are worth adding even with the flag left at `2`: the Cover then follows whatever `config.settings.blockModel` holds, and `BlockWrapper` in its view reads the same value.
+Under v2, the category has no effect, because only v3 renders the `category-*` class.
+
 ```{warning}
 The file matters here, and so does the position within it.
 
-{file}`src/index.ts` calls `installSettings` before `installBlocks`, so at the time {file}`config/settings.ts` runs, `config.blocks.blocksConfig.cover` does not exist yet—putting these lines there alongside `config.settings.blockModel = 3` throws. They have to run after the block is registered, and after the flag is set, which {file}`config/blocks.ts` satisfies on both counts.
+{file}`src/index.ts` calls `installSettings` before `installBlocks`, so at the time {file}`config/settings.ts` runs, `config.blocks.blocksConfig.cover` does not exist yet, and the lines above would throw an error there.
+They have to run after the block is registered, and after the flag is set, which {file}`config/blocks.ts` satisfies on both counts.
 ```
 
-Add a category of your own only when a block genuinely spaces differently from all four. When you do, name it for the family it opens rather than for the block that prompted it, and remember that a category only means something if your stylesheets act on the `category-*` class it produces.
+Then give the category its rules.
+Create {file}`src/theme/_categories.scss`:
 
-Vertical spacing between blocks is provided by the **upper block**:
-- Block content should be flush with top of container
-- Bottom padding creates space for following block
-- Different category combinations may have specific spacing adjustments
-
-### View Mode Structure
+```scss
+// Block Model v3 spacing for the `showcase` category: full-width sections
+// with their own background and padding, such as the Cover block.
+// VLT writes its category rules for `:not(.blocks-group-wrapper) > .block`,
+// which matches the blocks that Block Model v3 renders, and these rules
+// follow the same pattern.
+:not(.blocks-group-wrapper) > .block.category-showcase {
+  // A showcase keeps its padding inside its own background, so the space
+  // before the next block goes on the outer container.
+  padding-bottom: $block-vertical-space;
+
+  // Leave more space before text and buttons, and none before a separator.
+  &:has(+ .category-inline),
+  &:has(+ .category-action) {
+    padding-bottom: $spacing-xlarge;
+  }
 
-```tsx
-<div
-  style="$StyleWrapperStyles"
-  className="block $type category-$category $StyleWrapperClassNames"
->
-  <div className="block-inner-container">
-    {View component}
-  </div>
-</div>
+  &:has(+ .category-separator) {
+    padding-bottom: 0;
+  }
+}
 ```
 
-### Edit Mode Structure
+Import the partial at the end of {file}`src/theme/_main.scss`:
 
-```tsx
-<div
-  style="$StyleWrapperStyles"
-  className="block $type category-$category $StyleWrapperClassNames"
->
-  <div className="block-inner-container">
-    {Edit component}
-  </div>
-  <div className="block-edit-helpers">
-    {/* Delete block button, move block buttons, etc. */}
-  </div>
-</div>
+```scss
+@import './categories';
 ```
 
-Notice how the actual block content remains identical in both modes, while the framework containers handle all the differences in layout and editing functionality.
-### The `volto-bm3-compat` add-on
+Unlike `cards`, `showcase` sets no width, so the Cover's own stylesheet still decides it, and the Block Width control keeps working.
 
-Block Model v3 changes the markup a block renders into, so blocks written against the older model need their styles adapting. `@kitconcept/volto-bm3-compat` bridges that gap, and VLT declares it as an add-on of its own, so it is already in your dependency tree if you followed the install chapter.
+### The `volto-bm3-compat` add-on
 
-Check the block's repository for the "BMv3 ready" banner before enabling the new model on a block you did not write.
+`@kitconcept/volto-bm3-compat` provides the `BlockWrapper` component that you used in the Cover view.
+It lets one view work under both block models, rendering the wrappers that v2 needs and leaving them out under v3.
+VLT depends on it and declares it as an add-on, and you also listed it in your project add-on in the first chapter, because your view imports from it.
 
 ## Checkpoint
 
-- `config.settings.vlt.components` lists the nine swappable roles, each still set to `vlt`. Naming a component that was never registered under one of them falls back to VLT's own rather than rendering nothing.
-- The Signal sign-up form appears above the footer on every page.
-- A Listing block set to the **Robot Fleet** variation shows each charge level as a labelled bar, the Book buttons line up along the bottom of the cards whatever the description lengths, and tabbing through the page reaches every robot title as a link.
+- The Signal sign-up form appears at the top of the footer on every page.
+- A Listing block set to the **Robot Fleet** variation shows each charge level as a labelled bar, the Book buttons line up along the bottom of the cards whatever the description lengths, selecting a Book button does not open the robot's page, a robot without a photo shows a placeholder, and tabbing through the page reaches every robot title as a link.
 - The same robot in a Teaser block renders the same title, description, and charge bar as it does in the fleet listing.
-- If—and only if—you enabled Block Model v3, a Slate block renders inside a `.block-inner-container` and looks the same in edit mode as in view mode. With the flag left at `2`, as the Robotarium leaves it, every block still renders through the v2 path.
+- If—and only if—you enabled Block Model v3, a Text block renders inside a `.block-inner-container` and looks the same in edit mode as in view mode, and the Cover renders with the `category-showcase` class and still follows its Block Width control. With the flag left at `2`, as the Robotarium leaves it, blocks render as before.
 
 ## Further Reading
 
@@ -1143,5 +1149,4 @@ Check the block's repository for the "BMv3 ready" banner before enabling the new
 - [Slots reference](https://volto-light-theme.readthedocs.io/reference/slots.html)
 - [Card primitive reference](https://volto-light-theme.readthedocs.io/reference/card.html)
 - [Summary components](https://volto-light-theme.readthedocs.io/how-to-guides/summary.html)
-- [Site customization](https://volto-light-theme.readthedocs.io/conceptual-guides/site-customization.html)
 - [Block Model v3](https://volto-light-theme.readthedocs.io/conceptual-guides/block-model-v3.html)
diff --git a/docs/customizing-volto-light-theme/block-development-widgets.md b/docs/customizing-volto-light-theme/block-development-widgets.md
index 565e2ec60..f5e199dfd 100644
--- a/docs/customizing-volto-light-theme/block-development-widgets.md
+++ b/docs/customizing-volto-light-theme/block-development-widgets.md
@@ -9,148 +9,221 @@ myst:
 
 # Block Development, Widgets & Integration
 
-## Understanding VLT Widgets
+## Widgets for Block Styling
 
-VLT provides powerful widgets for block configuration that work with the StyleWrapper system.
+A block's styling options are ordinary schema fields, rendered by a handful of widgets.
+Some of these widgets come with Volto, and some with VLT.
+This section introduces the ones you will meet in this chapter and in VLT's own blocks.
+The [VLT widgets reference](https://volto-light-theme.readthedocs.io/reference/widgets.html) covers them in more detail.
 
-### BlockWidth Widget
+| Widget | Provided by | Stores | Used for |
+| --- | --- | --- | --- |
+| `blockWidth` | Volto | a width token, such as `default` | the width of a block, resolved through `config.blocks.widths` |
+| `blockAlignment` | Volto | an alignment token, such as `center` | the alignment of a block's content, resolved through `config.blocks.alignments` |
+| `size` | Volto | a size token: `s`, `m`, or `l` | the size of media, resolved through `config.blocks.sizes` |
+| `colorSwatch`, also registered as `color_picker` | VLT | the name of a palette entry | block themes and other curated palettes |
+| `colorPicker` | VLT | a hex color | a free choice of color, as in the theme behavior |
+| `object_list` | VLT, replacing Volto's widget of the same name | a list of objects | repeating items, such as header actions and footer links |
+| `softTextWidget` and `softTextareaWidget` | VLT | text | text with a recommended maximum length |
 
-Controls the content width of blocks:
+### Width, Alignment, and Size
+
+`blockWidth` and `blockAlignment` let editors pick one of a few buttons:
 
 ```javascript
 {
   widget: 'blockWidth',
   title: 'Block Width',
   default: 'default',
+  actions: config.blocks.widths.map((width) => width.name),
 }
 ```
 
-### BlockAlignment Widget
-
-Controls content alignment within blocks:
-
 ```javascript
 {
   widget: 'blockAlignment',
   title: 'Alignment',
   default: 'center',
+  actions: config.blocks.alignments.map((alignment) => alignment.name),
 }
 ```
 
-### ColorSwatch Widget
+Always pass the token names as `actions`, as shown above.
+Without `actions`, both widgets use a default list whose entries carry their own style objects, and the widget then stores the style object instead of the token.
+{ref}`Step 6 of the Cover block <light-theme-cover-actions-label>` explains the consequences.
+
+VLT resolves the tokens only for fields named `blockWidth:noprefix` and `align:noprefix`, as {ref}`the previous chapter <light-theme-style-fields-label>` explains.
 
-Lets editors pick from a curated palette instead of entering free-form values.
-Each entry follows the `StyleDefinition` type from `@plone/types`, and you should always provide a `default` option so the field has a predictable fallback:
+`size` selects a size from a default list of three:
 
 ```javascript
 {
-  widget: 'colorSwatch',
-  title: 'Background color',
-  default: 'default',
-  colors: [
-    {
-      name: 'default',
-      label: 'Default',
-      style: {
-        '--theme-color': '#fff',
-        '--theme-foreground-color': '#000',
-      },
+  widget: 'size',
+  title: 'Size',
+  default: 'm',
+}
+```
+
+The stored values are the tokens `s`, `m`, and `l`.
+The names Small, Medium, and Large are only their labels, so `default` must be one of the tokens.
+The default entries of `size` carry no styles, so it stores the tokens even without `actions`.
+When the field is named `size:noprefix`, VLT maps each token to the `--media-size` custom property through `config.blocks.sizes`:
+
+```typescript
+config.blocks.sizes = [
+  { style: { '--media-size': 'var(--size-small)' }, name: 's', label: 'Small' },
+  { style: { '--media-size': 'var(--size-medium)' }, name: 'm', label: 'Medium' },
+  { style: { '--media-size': 'var(--size-large)' }, name: 'l', label: 'Large' },
+];
+```
+
+All three widgets are built on Volto's `buttons` widget, which you can also use for your own single-choice fields.
+It accepts a list of `actions`, an `actionsInfoMap` with the icon and the label of each action, and `filterActions` to show only some of the actions.
+
+### Palettes: `colorSwatch`
+
+`colorSwatch` lets editors pick from a curated palette instead of entering free-form values.
+Each entry follows the `StyleDefinition` type from `@plone/types`.
+Always provide a `default` entry, so that the field has a predictable fallback.
+
+The following schema enhancer adds such a field to the `styles` object of a block.
+Like the Cover block's enhancer later in this chapter, it only works when it runs after VLT's `defaultStylingSchema`:
+
+```javascript
+const colors = [
+  {
+    name: 'default',
+    label: 'Default',
+    style: {
+      '--theme-color': '#fff',
+      '--theme-foreground-color': '#000',
     },
-    {
-      name: 'grey',
-      label: 'Grey',
-      style: {
-        '--theme-color': '#ecebeb',
-        '--theme-foreground-color': '#000',
-      },
+  },
+  {
+    name: 'grey',
+    label: 'Grey',
+    style: {
+      '--theme-color': '#ecebeb',
+      '--theme-foreground-color': '#000',
     },
-  ],
-}
+  },
+];
+
+const myColorSchemaEnhancer = ({ schema }) => {
+  schema.properties.styles.schema.fieldsets[0].fields.push('myColorField');
+  schema.properties.styles.schema.properties.myColorField = {
+    widget: 'colorSwatch',
+    title: 'My color',
+    default: 'default',
+    colors,
+  };
+  return schema;
+};
 ```
 
-The widget stores the chosen color's `name` token, and the StyleWrapper adds that token as a CSS class on the block, so you can target it in your stylesheets.
-If you also want the CSS custom properties injected inline, register a `styleFieldDefinition` utility for the field name used in the schema:
+The widget stores the `name` of the chosen entry, and the StyleWrapper turns it into a class on the block, such as `has--myColorField--grey`, which you can target in your stylesheets.
+To also inject the entry's custom properties as inline styles, register a `styleFieldDefinition` utility under the field name:
 
 ```javascript
 config.registerUtility({
   name: 'myColorField',
   type: 'styleFieldDefinition',
-  method: (props) => colors,
+  method: () => colors,
 });
 ```
 
+VLT only looks up these utilities for the fields inside a block's `styles` object, which is why the example adds the field there.
+
 ```{note}
-This is the recommended way to use this widget, since it decouples the styles from the CSS and keeps a single source of truth for the color definitions.
+This is the recommended way to use this widget, because the same `colors` list feeds both the widget and the styles, which keeps a single source of truth for the palette.
 ```
 
-### ObjectList Widget
+VLT registers the same component as `color_picker`.
+That is the widget `defaultStylingSchema` uses for the **Background color** field, with the palettes passed in a `themes` prop instead of `colors`.
+VLT also registers `themeColorSwatch`, a variant that always shows the palettes in `config.blocks.themes`.
+
+### Free Colors: `colorPicker`
 
-Allows introducing a list of ordered objects with drag and drop:
+`colorPicker` is a color picker with a visual chooser and a hex input.
+The theme behavior uses it for its five color fields.
+
+For fields listed in `config.settings.colorMap`, `colorPicker` also renders `ColorContrastChecker`.
+This component warns the editor when the contrast between the field and its paired color is below 4.5:1, following the WCAG guidelines.
+The pairs and their default values are defined like this:
 
 ```javascript
-{
-  widget: 'object_list',
-  title: 'Items',
-  schemaName: 'mySchemaName',
-}
+config.settings.colorMap = {
+  primary_color: {
+    colorPair: 'primary_foreground_color',
+    default: '#ffffff',
+  },
+  primary_foreground_color: {
+    colorPair: 'primary_color',
+    default: '#000000',
+  },
+  // ... and the same for the secondary and accent pairs
+};
 ```
 
-### ColorPicker Widget
+You can reuse the checker in your own color widget.
+Render it after the field, and only for fields listed in `colorMap`, as VLT's `colorPicker` does, because it throws an error for any other field.
+It compares hex colors with the paired field of the content being edited, so it is meant for content fields such as the theme behavior's, not for block settings.
 
-A real color picker, with an RGB visual color chooser and a `hex` color field:
+```jsx
+import FormFieldWrapper from '@plone/volto/components/manage/Widgets/FormFieldWrapper';
+import config from '@plone/volto/registry';
+import ColorContrastChecker from '@kitconcept/volto-light-theme/components/Widgets/ColorContrastChecker';
 
-```javascript
-{
-  widget: 'colorPicker',
-  title: 'Custom color',
-}
+const MyColorWidget = (props) => {
+  const { id, value, onChange } = props;
+
+  return (
+    <>
+      <FormFieldWrapper {...props}>
+        <input
+          id={`field-${id}`}
+          type="color"
+          value={value || '#ffffff'}
+          onChange={(event) => onChange(id, event.target.value)}
+        />
+      </FormFieldWrapper>
+      {config.settings.colorMap[id] && <ColorContrastChecker {...props} />}
+    </>
+  );
+};
+
+export default MyColorWidget;
 ```
 
-### color_picker Widget
+### Lists: `object_list`
 
-A Semantic UI-free drop-in replacement that overrides Volto's `color_picker` widget.
-Given an array of color definitions, it displays the colors that editors can choose:
+VLT replaces Volto's `object_list` widget with one that supports reordering by drag and drop.
+It stores a list of objects, each with a generated `@id`.
+The shape of each object comes from a `schema` prop, or from `schemaName`, the name of a schema registered as a utility.
+The schema can be a schema object, or a function that returns one:
 
 ```javascript
-{
-  widget: 'color_picker',
-  title: 'Color',
-  colors: [
-    { name: 'default', label: 'Default' },
-    { name: 'grey', label: 'Grey' },
-  ],
-}
+config.registerUtility({
+  name: 'mySchemaName',
+  type: 'schema',
+  method: mySchema,
+});
 ```
 
-### Size Widget
-
-Selects the block size from a default list of three values.
-The stored values are the tokens `s`, `m`, and `l`. The names Small, Medium, and Large are only their labels, so a `default` must be one of the tokens:
-
 ```javascript
 {
-  widget: 'size',
-  title: 'Size',
-  default: 'm',
+  widget: 'object_list',
+  title: 'Items',
+  schemaName: 'mySchemaName',
 }
 ```
 
-VLT maps each token to the `--media-size` custom property through `config.blocks.sizes`, resolved by the `size:noprefix` style field:
-
-```typescript
-config.blocks.sizes = [
-  { style: { '--media-size': 'var(--size-small)' }, name: 's', label: 'Small' },
-  { style: { '--media-size': 'var(--size-medium)' }, name: 'm', label: 'Medium' },
-  { style: { '--media-size': 'var(--size-large)' }, name: 'l', label: 'Large' },
-];
-```
-
-Like the BlockAlignment widget, it is based on the Buttons component under the hood, so its actions and the styles they apply are configurable.
+VLT's header actions, footer links, and footer logos fields work this way, with the schemas `headerActions`, `footerLinks`, and `footerLogos`.
 
-### SoftText and SoftTextarea Widgets
+### Text With a Soft Limit
 
-`softTextWidget` and `softTextareaWidget` behave like the `text` and `textarea` widgets, but they display a real-time character count while typing.
-When the count exceeds the limit set in `softMaxLength`, a notification appears, but the editor is still allowed to save the content.
+`softTextWidget` and `softTextareaWidget` behave like the `text` and `textarea` widgets, but they display a character count while the editor types.
+When the count exceeds the limit set in `softMaxLength`, a warning appears, but the editor can still save the content.
 
 These widgets are configured from the backend, with `directives.widget` and its `frontendOptions`:
 
@@ -169,65 +242,15 @@ seo_title = schema.TextLine(
 )
 ```
 
-### ColorContrastChecker Component
-
-Not a widget itself, but a component that calculates the contrast ratio between two colors following the WCAG accessibility guidelines.
-It is provided by VLT, at `@kitconcept/volto-light-theme/components/Widgets/ColorContrastChecker`.
-Add it after a color input field in your own widget to warn the editor in real time about insufficient contrast:
-
-```jsx
-import ContrastChecker from '@kitconcept/volto-light-theme/components/Widgets/ColorContrastChecker';
-
-const MyColorWidget = (props) => {
-  return (
-    <>
-      <FormFieldWrapper {...props} />
-      <ContrastChecker {...props} />
-    </>
-  );
-};
-
-export default MyColorWidget;
-```
-
-It accepts hex color codes, and compares the value of the field against its paired color.
-The pairings and their defaults are defined in `config.settings.colorMap`:
-
-```javascript
-config.settings.colorMap = {
-  primary_color: {
-    colorPair: 'primary_foreground_color',
-    default: '#ffffff',
-  },
-  primary_foreground_color: {
-    colorPair: 'primary_color',
-    default: '#000000',
-  },
-};
-```
-
-### Buttons Component
-
-Another helper rather than a widget, used to build widgets that show a list of buttons where a single value can be toggled.
-The BlockAlignment and Size widgets are built on top of it.
-You can pass it a configurable list of `actions`, along with the icon and the i18n message used for each one in `actionsInfoMap`, and filter out the default actions you don't want with `filterActions`.
-
-```{note}
-As of VLT 8.0.0-alpha.5, four of these components live in Volto core rather than in VLT: `ButtonsWidget`, `BlockAlignment`, `BlockWidth`, and `Size`.
-If you are on Volto 19.0.0-alpha.12 or later, import them from `@plone/volto/components/manage/Widgets/` instead of from VLT.
-
-`ColorContrastChecker` was not part of that move and is still provided by VLT.
-```
-
 (cover-block-label)=
 
 ## Creating a Custom Cover Block
 
-Let's build a cover block step by step, starting with a basic implementation and then enhancing it with VLT widgets.
+This section builds a cover block step by step, starting with a basic implementation and then adding VLT's styling fields to it.
 
 ### Step 1: Create Basic Block Schema
 
-Create `src/components/blocks/Cover/schema.ts`:
+Create {file}`src/components/blocks/Cover/schema.ts`:
 
 ```typescript
 import { defineMessages } from 'react-intl';
@@ -293,78 +316,62 @@ export { coverBlockSchema };
 
 ### Step 2: Create View Component
 
-Before writing any markup, note what the block view is **not** responsible for.
-Volto already wraps every block, and under Block Model v3 it wraps it twice:
+Before writing any markup, note which wrappers the view is responsible for.
+VLT supports two block models, and they wrap a block differently:
+
+- Under **Block Model v2**, the default, the block view renders its own outer element, `div.block.cover`. The renderer passes it the block's classes and inline styles.
+- Under **Block Model v3**, VLT's renderer adds two wrappers itself, and renders the view inside them:
 
 ```html
-<div class="block cover">              <!-- rendered for you -->
-  <div class="block-inner-container">  <!-- rendered for you under BM3 -->
+<div class="block cover">              <!-- added by VLT under v3 -->
+  <div class="block-inner-container">  <!-- added by VLT under v3 -->
     ...your markup starts here...
 ```
 
-The outer `.block` carries the block's identity and its theme; the inner container carries the width and the alignment.
+The outer element carries the block's identity and its theme; the inner container carries the width and the alignment.
 This split is what lets a block have a background that behaves independently of its content width, and it is described in full in {ref}`the two-container system <bm3-two-container-label>`.
 
-A block view that renders its own `.block` wrapper therefore produces a duplicate.
-The way to stay correct under both block models is `BlockWrapper` from `@kitconcept/volto-bm3-compat`, which renders the wrappers under Block Model v2 and steps aside under v3, where Volto renders them itself.
+A view that always renders its own `div.block` would be wrapped twice under v3.
+`BlockWrapper` from `@kitconcept/volto-bm3-compat` avoids that.
+It renders the outer element, and an optional inner element that you pass as `ExtraWrapper`, only when the block uses v2.
+With it, the view produces the same structure under both models.
 
-Create `src/components/blocks/Cover/View.tsx`:
+Create {file}`src/components/blocks/Cover/View.tsx`:
 
 ```tsx
 import config from '@plone/volto/registry';
-import { flattenToAppURL, isInternalURL } from '@plone/volto/helpers/Url/Url';
 import { BlockWrapper } from '@kitconcept/volto-bm3-compat';
 import type { BlockViewProps } from '@plone/types';
 import type { ReactNode } from 'react';
 
-// Under block model 2, BlockWrapper renders `.block.cover` and then this
-// ExtraWrapper. Under block model 3 it renders neither, because Volto already
-// emits both. Either way the result is
-// `.block.cover > .block-inner-container > ...`.
+// Under Block Model v2, BlockWrapper renders `.block.cover` and then this
+// inner container. Under v3 it renders neither, because VLT's renderer adds
+// both. Either way the result is `.block.cover > .block-inner-container > ...`.
 const InnerContainer = (props: { children: ReactNode }) => (
   <div className="block-inner-container">{props.children}</div>
 );
 
 const CoverView = (props: BlockViewProps) => {
   const { title, subtitle, backgroundImage } = props?.data || {};
-
-  const hasImage = backgroundImage?.[0]?.['@id'];
-
-  let renderedImage = null;
-  if (hasImage) {
-    const Image = config.getComponent('Image').component;
-    const imageItem = backgroundImage[0];
-
-    if (Image) {
-      renderedImage = (
-        <Image
-          item={{
-            '@id': imageItem['@id'],
-            image_field: imageItem.image_field,
-            image_scales: imageItem.image_scales,
-          }}
-          alt=""
-          loading="lazy"
-          responsive
-        />
-      );
-    } else {
-      const src = imageItem['@id'];
-      renderedImage = (
-        <img
-          src={
-            isInternalURL(src) ? `${flattenToAppURL(src)}/@@images/image` : src
-          }
-          alt=""
-          loading="lazy"
-        />
-      );
-    }
-  }
+  const imageItem = backgroundImage?.[0];
+  const Image = config.getComponent('Image').component;
 
   return (
     <BlockWrapper {...props} ExtraWrapper={InnerContainer}>
-      {hasImage && <div className="cover-image-wrapper">{renderedImage}</div>}
+      {imageItem?.['@id'] && (
+        <div className="cover-image-wrapper">
+          <Image
+            item={{
+              '@id': imageItem['@id'],
+              image_field: imageItem.image_field,
+              image_scales: imageItem.image_scales,
+            }}
+            alt=""
+            loading="lazy"
+            responsive
+          />
+        </div>
+      )}
 
       <div className="cover-text">
         {title && <h2 className="cover-title">{title}</h2>}
@@ -377,12 +384,13 @@ const CoverView = (props: BlockViewProps) => {
 export default CoverView;
 ```
 
+The view renders the image with Volto's `Image` component, which picks a suitable image scale for the space available.
+
 ### Step 3: Create Edit Component
 
-Create `src/components/blocks/Cover/Edit.tsx`:
+Create {file}`src/components/blocks/Cover/Edit.tsx`:
 
 ```tsx
-import React from 'react';
 import { useIntl } from 'react-intl';
 import SidebarPortal from '@plone/volto/components/manage/Sidebar/SidebarPortal';
 import { BlockDataForm } from '@plone/volto/components/manage/Form';
@@ -402,7 +410,7 @@ const CoverEdit = (props: BlockEditProps) => {
           {...props}
           data={data}
           block={block}
-          schema={coverBlockSchema({ props, intl })}
+          schema={coverBlockSchema({ intl })}
           onChangeBlock={onChangeBlock}
           formData={data}
           onChangeField={(id: string, value: any) => {
@@ -420,9 +428,11 @@ const CoverEdit = (props: BlockEditProps) => {
 export default CoverEdit;
 ```
 
+`BlockDataForm` applies the block's `schemaEnhancer` from its configuration to the schema you pass, which is what makes the styling fields from Step 6 appear in the sidebar.
+
 ### Step 4: Register the Basic Block
 
-Edit `src/config/blocks.ts`. Do not replace the file: it already holds the block themes from the previous chapter.
+Edit {file}`src/config/blocks.ts`. Do not replace the file: it already holds the block themes from the previous chapter.
 Add the imports at the top of the file, and the registration inside the existing `install` function:
 
 ```typescript
@@ -456,7 +466,7 @@ export default function install(config: ConfigType) {
 ```{note}
 Give project blocks their own key, and follow the convention every other block in the registry uses: a lowercase single word such as `teaser`, `banner`, or `slider`, reserving camelCase for genuinely multi-word names like `gridBlock`.
 
-The icon is a separate matter. Icon assets are not tied to block names, and {file}`hero.svg` is the one that depicts this layout, so it we will use it in this example.
+The icon is a separate matter. Icon assets are not tied to block names, and {file}`hero.svg` is the one that depicts this layout, so this example uses it.
 ```
 
 ### Step 5: Add Basic Block Styles
@@ -464,7 +474,7 @@ The icon is a separate matter. Icon assets are not tied to block names, and {fil
 The block has no styling fields yet, so this step sets up **structure only**.
 Everything that depends on a widget—the width, the alignment, the theme color—arrives in Step 8, once the fields that produce those properties exist.
 
-Create `src/theme/blocks/_cover.scss`:
+Create {file}`src/theme/blocks/_cover.scss`:
 
 ```scss
 .block.cover {
@@ -528,40 +538,95 @@ Create `src/theme/blocks/_cover.scss`:
 }
 ```
 
-Two decisions worth calling out.
+Two decisions are worth calling out.
 
 **The width goes on `.block-inner-container`, not on `.block`.**
 That is the two-container split: the outer element is the block's full extent, the inner one is where content is constrained. Putting `max-width` on the outer element instead fights VLT, which already constrains inner containers, and it makes a full-width block impossible.
 
 **`min-height` is load-bearing.**
-The image sits in an absolutely positioned wrapper and contributes no height, so without it a cover with an image collapses to nothing—at which point the alignment control in Step 8 will appear to do nothing, because there is no space to align within.
+The image sits in an absolutely positioned wrapper and contributes no height.
+Without `min-height`, the cover is only as tall as its text, and the image is cropped to that strip.
 
-Import it in `src/theme/_main.scss`:
+Import the partial in {file}`src/theme/_main.scss`, next to the other block partials:
 
 ```scss
-@import './blocks/button';
 @import './blocks/cover';
-@import './blocks/grid';
-@import './blocks/slider';
-@import './blocks/teaser';
 ```
 
-### Step 6: Enhance with VLT Widgets
+(light-theme-cover-actions-label)=
 
-Now let's add VLT's widgets for block width and alignment, by adding a schema enhancer alongside the block schema.
+### Step 6: Add Width and Alignment Fields
 
-```{important}
+Now add width and alignment fields to the block, with a schema enhancer next to the block schema. VLT resolves both fields, as described in {ref}`the previous chapter <light-theme-style-fields-label>`.
+
+:::{important}
 The enhancer below **extends** the styling fieldset; it does not create one.
-`schema.properties.styles` only exists once VLT's `defaultStylingSchema` has run, so this enhancer is meaningful only when composed after it—which is what Step 7 does:
+`schema.properties.styles` only exists once VLT's `defaultStylingSchema` has run, so this enhancer only works when it is composed after it, which is what Step 7 does:
 
-    schemaEnhancer: composeSchema(defaultStylingSchema, coverSchemaEnhancer)
+```typescript
+schemaEnhancer: composeSchema(defaultStylingSchema, coverSchemaEnhancer),
+```
 
-Registered on its own, it throws, because `schema.properties.styles` is `undefined`.
+Registered on its own, it throws an error, because `schema.properties.styles` is `undefined`.
 This is also why the block gets its **Background color** control for free: that field comes from `defaultStylingSchema`, not from anything you write here.
+:::
+
+Make three changes to {file}`src/components/blocks/Cover/schema.ts`.
+
+First, import the registry at the top of the file:
+
+```typescript
+import config from '@plone/volto/registry';
+```
+
+Second, add two messages to the `messages` object:
+
+```typescript
+  blockWidth: {
+    id: 'Block Width',
+    defaultMessage: 'Block Width',
+  },
+  textAlignment: {
+    id: 'Text Alignment',
+    defaultMessage: 'Text Alignment',
+  },
 ```
 
-Replace the whole of `src/components/blocks/Cover/schema.ts` with the following. It repeats the schema from Step 1, adds two messages, and exports the new enhancer:
+Third, add the enhancer after `coverBlockSchema`, and export it as well, by replacing the `export` line at the end of the file:
 
+```typescript
+// Schema enhancer that adds the width and alignment styling fields.
+// Only meaningful when composed *after* VLT's `defaultStylingSchema`, which is
+// what creates `schema.properties.styles`.
+const coverSchemaEnhancer = ({ schema, intl }) => {
+  // Add custom fields to the styling schema at the beginning
+  schema.properties.styles.schema.fieldsets[0].fields = [
+    'align:noprefix',
+    'blockWidth:noprefix',
+    ...schema.properties.styles.schema.fieldsets[0].fields,
+  ];
+
+  schema.properties.styles.schema.properties['align:noprefix'] = {
+    widget: 'blockAlignment',
+    title: intl.formatMessage(messages.textAlignment),
+    default: 'center',
+    actions: config.blocks.alignments.map((alignment) => alignment.name),
+  };
+
+  schema.properties.styles.schema.properties['blockWidth:noprefix'] = {
+    widget: 'blockWidth',
+    title: intl.formatMessage(messages.blockWidth),
+    default: 'default',
+    actions: config.blocks.widths.map((width) => width.name),
+  };
+
+  return schema;
+};
+
+export { coverBlockSchema, coverSchemaEnhancer };
+```
+
+::::{dropdown} The complete schema.ts after this step
 ```typescript
 import { defineMessages } from 'react-intl';
 import config from '@plone/volto/registry';
@@ -630,10 +695,10 @@ const coverBlockSchema = (props) => {
   };
 };
 
-// Schema enhancer to add VLT widget styling fields.
+// Schema enhancer that adds the width and alignment styling fields.
 // Only meaningful when composed *after* VLT's `defaultStylingSchema`, which is
 // what creates `schema.properties.styles`.
-const coverSchemaEnhancer = ({ formData, schema, intl }) => {
+const coverSchemaEnhancer = ({ schema, intl }) => {
   // Add custom fields to the styling schema at the beginning
   schema.properties.styles.schema.fieldsets[0].fields = [
     'align:noprefix',
@@ -660,23 +725,25 @@ const coverSchemaEnhancer = ({ formData, schema, intl }) => {
 
 export { coverBlockSchema, coverSchemaEnhancer };
 ```
+::::
 
 Two details in that enhancer decide whether it works at all.
 
 **The field names must end in `:noprefix`.**
-As covered in the previous chapter, `align:noprefix` and `align` are different field names.
-VLT registers its style definitions under the literal names `align:noprefix` and `blockWidth:noprefix`, so a field called `align` matches nothing: the `--block-alignment` property is never injected, and the styles in Step 8 that read it silently do nothing.
-The failure is quiet—the buttons still appear in the sidebar, they just have no effect.
-
-Match the names VLT registers, and you inherit its behavior. What the suffix suppresses is the generated `has--align--center` class, and the more your styling is driven by custom properties—as the Cover block's is—the less those classes matter.
+As covered in {ref}`the previous chapter <light-theme-style-fields-label>`, `align:noprefix` and `align` are different field names.
+VLT registers its style definitions under the literal names `align:noprefix` and `blockWidth:noprefix`, so a field called `align` matches none of them.
+The `--block-alignment` property is then never injected, and the styles in Step 8 that read it have no effect.
+The mistake is easy to miss: the buttons still appear in the sidebar, but the text does not move.
 
-**Pass `actions` from `config.blocks`.**
-Both widgets fall back to a built-in list when `actions` is omitted, and those built-in defaults are close to VLT's but not identical—Volto's `full` width resolves to `unset` where VLT's resolves to `100%`.
-Deriving the actions from `config.blocks.alignments` and `config.blocks.widths` keeps the block in step with the theme, and with any width or alignment your project adds.
+**Pass the token names as `actions`.**
+Without `actions`, the widgets fall back to Volto's default list, and each default entry carries its own style object, such as `{ '--block-width': 'unset' }` for Full.
+When the chosen entry has a style object, the widget stores that object instead of the token.
+The block would then save a style object rather than `"full"`, skip VLT's definitions in `config.blocks.widths`, and get the class `has--block-width--[object Object]`.
+Mapping `config.blocks.alignments` and `config.blocks.widths` to their names makes the widgets store tokens, and keeps the block in step with the theme, including any width or alignment your project adds.
 
 ### Step 7: Update Block Registration with Schema Enhancer
 
-Back in `src/config/blocks.ts`, add the two new imports and the `schemaEnhancer` key to the registration you wrote in Step 4:
+Back in {file}`src/config/blocks.ts`, add the two new imports and the `schemaEnhancer` key to the registration you wrote in Step 4:
 
 ```typescript
 import type { ConfigType } from '@plone/registry';
@@ -714,33 +781,39 @@ export default function install(config: ConfigType) {
 
 `composeSchema` runs its arguments in order, so `defaultStylingSchema` creates the styling fieldset and `coverSchemaEnhancer` then extends it. Reverse them and the second enhancer runs against a schema that has no `styles` property yet.
 
-```{tip}
-The same technique adds VLT's theming to a block **you did not write**—one from a third-party add-on, or a core Volto block. The only difference is that such a block may already have a `schemaEnhancer` of its own, which you must preserve:
+(light-theme-third-party-styling-label)=
 
-    config.blocks.blocksConfig.<blockId> = {
-      ...config.blocks.blocksConfig.<blockId>,
-      schemaEnhancer: composeSchema(
-        config.blocks.blocksConfig.<blockId>.schemaEnhancer,
-        defaultStylingSchema,
-      ),
-    };
+:::{tip}
+The same technique adds VLT's theming to a block **you did not write**—one from a third-party add-on, or a core Volto block.
+The only difference is that such a block may already have a `schemaEnhancer` of its own, which you must preserve.
+`composeSchema` skips an enhancer that is `undefined`, so this works whether or not the block has one:
 
+```typescript
+config.blocks.blocksConfig.<blockId> = {
+  ...config.blocks.blocksConfig.<blockId>,
+  schemaEnhancer: composeSchema(
+    config.blocks.blocksConfig.<blockId>.schemaEnhancer,
+    defaultStylingSchema,
+  ),
+};
 ```
+:::
 
 ### Step 8: Update Styles to Use Widget Values
 
-The structure from Step 5 stays as it is. This step connects it to the three custom properties that now exist, because the schema enhancers from Steps 6 and 7 are in place: `--block-width`, `--block-alignment`, and `--theme-color`.
+The schema enhancers from Steps 6 and 7 now provide the custom properties that the styles can read: `--block-width` and `--block-alignment` from the new fields, and the theme properties, such as `--theme-color`, from the **Background color** control.
 
-Make these four changes in `src/theme/blocks/_cover.scss`:
+Replace the whole of {file}`src/theme/blocks/_cover.scss` with the following version.
+Compared with Step 5, it adds the five numbered changes:
 
 ```scss
-// 1. Lift VLT's layout-width cap. See the explanation below.
+// 1. Lift VLT's layout-width cap for this block. See the explanation below.
 #page-document .blocks-group-wrapper > .block.cover {
   max-width: 100%;
 }
 
 .block.cover {
-  // 2. The theme's foreground color, set by the Background color control.
+  // 2. The text color of the selected theme.
   color: var(--theme-foreground-color);
 
   .block-inner-container {
@@ -749,45 +822,87 @@ Make these four changes in `src/theme/blocks/_cover.scss`:
     overflow: hidden;
     min-height: 60vh;
 
-    // 3. Driven by the Block Width control, with the site default as a
-    //    fallback so the block stays sane if the field is ever removed.
+    // 3. The width chosen in Block Width, with the site default as a
+    //    fallback, so the block stays sane if the field is ever removed.
     max-width: var(--block-width, var(--default-container-width));
     align-items: center;
     padding: 4rem 2rem;
     margin-inline: auto;
 
-    // The theme's background. `background`, never `background-color` — see the
-    // warning below.
+    // 4. The background of the selected theme. Use `background`, not
+    //    `background-color`, so that gradient themes work as well.
     background: var(--theme-color);
   }
 
   .cover-text {
+    // Above the background image.
     position: relative;
     z-index: 1;
     display: flex;
     width: 100%;
     flex-direction: column;
 
-    // 4. Driven by the Text Alignment control.
+    // 5. The alignment chosen in Text Alignment.
     align-items: var(--block-alignment, start);
     gap: 1rem;
     text-align: var(--block-alignment, start);
 
-    // ... the rest is unchanged from Step 5 ...
+    .cover-title {
+      margin-bottom: $spacing-small;
+      font-size: 5rem;
+      line-height: 1.1;
+    }
+
+    .cover-subtitle {
+      margin-bottom: $spacing-small;
+      font-size: 2rem;
+      line-height: 1.3;
+      opacity: 0.9;
+    }
+  }
+
+  &:has(.cover-image-wrapper) {
+    color: #fff;
+  }
+
+  .cover-image-wrapper {
+    position: absolute;
+    z-index: 0;
+    inset: 0;
+
+    img {
+      width: 100%;
+      height: 100%;
+      object-fit: cover;
+      opacity: 0.7;
+    }
+
+    &::after {
+      position: absolute;
+      background: rgb(0 0 0 / 40%);
+      content: '';
+      inset: 0;
+    }
   }
 }
 ```
 
-Because the width and the background both sit on `.block-inner-container`, the Block Width control now resizes the whole visual unit—color, image, and text together—rather than only the text.
+The first rule is needed because VLT limits every block inside a block group to the layout width, with the selector `#page-document .blocks-group-wrapper > *`.
+Lifting that limit for the Cover lets a Full Width cover reach the edges of the page, and the inner container's `max-width` then decides the actual width.
+
+The image and the text both sit inside `.block-inner-container`, so the Block Width control resizes them together.
+The theme color behind the Cover still spans the whole width of the page, because VLT groups consecutive blocks that share a theme and paints the theme on the group.
+Change 4 repeats the theme background inside the Cover, where it shows through the partly transparent image.
+For why gradient themes need `background`, see {ref}`the warning about gradient palettes <light-theme-gradient-themes-label>`.
 
 ## Checkpoint
 
 Restart the frontend, then add a Cover block to the Robotarium landing page. Give it the title **Book a robot. Build something.**, a subtitle such as *Twelve units, one afternoon at a time*, and a workshop photo as the background image. Confirm that:
 
 - The block appears in the block chooser, listed as **Cover**.
-- The **Styling** tab of the sidebar shows **Alignment** and **Block Width** controls.
-- Changing the alignment moves the title and subtitle, and changing the width resizes the block. If the controls appear but nothing moves, check that the field names end in `:noprefix`.
-- Setting the width to **Full Width** takes the block edge to edge, background image included.
+- The **Styling** section of the block settings shows the **Text Alignment**, **Block Width**, and **Background color** controls.
+- Changing the alignment moves the title and subtitle, and changing the width resizes the image and the text. If the controls appear but nothing moves, check that the field names end in `:noprefix`.
+- On the published page, setting the width to **Full Width** takes the image from edge to edge.
 
 ```{seealso}
 A block can also offer more than one rendering of the same data, as the Listing block does with its variations.
@@ -798,4 +913,3 @@ That is covered in the next chapter, where the Robotarium gets a **Robot Fleet**
 
 - [Widgets reference](https://volto-light-theme.readthedocs.io/reference/widgets.html)
 - [Develop add-ons for VLT](https://volto-light-theme.readthedocs.io/how-to-guides/develop-add-ons.html)
-- [Image aspect ratio](https://volto-light-theme.readthedocs.io/reference/image-aspect-ratio.html)
diff --git a/docs/customizing-volto-light-theme/concepts.md b/docs/customizing-volto-light-theme/concepts.md
index f3cd98283..ef8675e61 100644
--- a/docs/customizing-volto-light-theme/concepts.md
+++ b/docs/customizing-volto-light-theme/concepts.md
@@ -13,43 +13,33 @@ myst:
 
 Rather than theme an abstract site, this training builds one: **the Robotarium**, a neighborhood workshop that lends robots the way a library lends books. Members browse the fleet, check what is charged and available, and book a unit for the afternoon.
 
-It is a small site with an ordinary shape—a fleet to list, a workshop to describe, and a way to visit—which is exactly what makes it useful here. Every VLT feature the training covers earns its place by solving something the Robotarium actually needs:
+Every VLT feature the training covers earns its place by solving something the Robotarium actually needs:
 
-| The site needs | You will learn |
-| --- | --- |
-| A look that is its own, not the default | Design tokens, color system, block themes |
-| A full-width opening on the landing page | Building a custom block with VLT's widgets |
-| A fleet listing showing charge levels | Summary components and listing variations |
-| A booking button on each robot | The Card primitive and its Actions slot |
-| A sign-up form above the footer | Slots |
+| The site needs | You will learn | Covered in |
+| --- | --- | --- |
+| A look that is its own, not the default | Design tokens, the color system, and block themes | {doc}`design-system-implementation` |
+| A full-width opening on the landing page | Building a custom block with VLT's widgets | {doc}`block-development-widgets` |
+| A fleet listing showing charge levels | Summary components and listing variations | {doc}`advanced-components-bm3` |
+| A booking button on each robot | The Card primitive and its Actions slot | {doc}`advanced-components-bm3` |
+| A newsletter sign-up at the top of the footer | Slots | {doc}`advanced-components-bm3` |
 
-The project add-on is called `robotarium` throughout. If you would rather build something else, every step works the same with your own name substituted; only the copy changes.
+The project is called `robotarium`, and Cookieplone names its frontend add-on `volto-robotarium`.
+If you would rather build something else, every step works the same with your own names substituted.
 
 ## Volto Light Theme Core Concepts
 
-Volto Light Theme (VLT) is a customizable theme built for the Volto frontend of the Plone CMS. It provides a foundation that aims to solve many common design challenges, while remaining flexible enough for customization. It's particularly valuable because it is based on real-world experience, while simultaneously embodying the Volto vision for the future. This module will help you understand the core concepts in VLT and create a mental map of its parts.
-
-### Base Styling
-
-VLT is designed with simplicity and a minimal aesthetic in mind. The three core principles are:
-
-- **Consistency**: Predictable design patterns across all components
-- **Accessibility**: WCAG compliant with contrast checkers and semantic HTML
-- **Intuitiveness**: Clear visual hierarchy and user-friendly interfaces
-
-### Customizable Variables
-
-VLT offers a set of CSS custom properties (variables) that allow developers to customize various design elements:
-
-- **Colors**: Using paired foreground/background color system
-- **Spatial relationships**: Container widths and spacing scales
-- **Layouts**: Three-width container system
+Volto Light Theme (VLT) is a customizable theme for the Volto frontend of Plone.
+It provides a foundation that solves many common design challenges, while remaining flexible enough for customization.
+It is based on real-world projects, and it follows the direction that Volto is taking.
 
-These variables can be easily overridden in your project to match the desired visual identity.
+Most of VLT's design decisions are CSS custom properties that your project can override: the color pairs, the container widths, and the palettes that editors apply to blocks.
+This section introduces each of them, so that you have a mental map of VLT's parts before you start building.
 
 ### Color System
 
-The color system is designed so that colors work in couples: a "background color" and a "foreground color". The "foreground color" is often called "text color" in other systems, but since we want to use this value for more than text—like icons or borders—this works better as a generic term. Colors that do not specify "foreground" in the name are meant to be background colors.
+The color system is designed so that colors work in pairs: a background color and a foreground color.
+Other systems often call the foreground color the text color, but VLT uses it for more than text, such as icons and borders, so it uses the more generic term.
+Colors that do not have "foreground" in their name are background colors.
 
 The main color properties for a project using VLT are:
 
@@ -75,28 +65,31 @@ VLT registers them with the CSS [`@property`](https://developer.mozilla.org/en-U
 }
 ```
 
-Registering them buys three things that matter for a theme:
+Registering them has three consequences that matter for a theme:
 
-- The `initial-value` is the default, so the property always resolves to a valid color even when nothing has set it.
+- The `initial-value` is the default, so the property always has a valid color, even when nothing sets it. For the same reason, a fallback such as `var(--accent-color, teal)` is never used.
 - The `<color>` syntax makes the value typed, so an invalid value is rejected instead of silently cascading.
-- Typed properties can be interpolated, so transitions and `color-mix()` behave predictably.
+- The browser can animate a typed property, so a transition from one color to another is smooth instead of jumping.
 
-You override them the same way as any other custom property, by assigning to them in `:root`.
+VLT registers `--background` the same way, with white as its default, and uses it as the default value of `--primary-color`.
+
+You override these properties the same way as any other custom property, by assigning to them in `:root`.
 
 ### Semantic Color Properties
 
-As an additional layer on top of the main color properties, we have set in place some semantic custom properties for the basic layout sections. As a default they use the values from the main color variables, but they can be detached if desired by setting new color values. However, leaving these color relationships as they are helps create a cohesive final design:
+On top of the main color properties, VLT declares semantic properties for the main layout sections.
+By default they take their values from the main color properties.
+You can set them to other colors, but keeping these relationships helps create a cohesive design:
 
 ```scss
 // Header
 --header-background: var(--primary-color);
---header-foreground: var(--primary-foreground-color);
 
 // Footer
 --footer-background: var(--secondary-color);
 --footer-foreground: var(--secondary-foreground-color);
 
-// Fat Menu
+// Fat menu
 --fatmenu-background: var(--accent-color);
 --fatmenu-foreground: var(--accent-foreground-color);
 
@@ -112,9 +105,13 @@ As an additional layer on top of the main color properties, we have set in place
 --link-color: #0070a2;
 ```
 
+VLT does not declare `--header-foreground` by default.
+The navigation items fall back to `--primary-foreground-color`, and the {ref}`theme behavior <light-theme-behavior-colors-label>` sets `--header-foreground` when an editor picks a navigation text color.
+
 Links are the one exception to the pattern above.
-By default `<a>` elements inherit `--theme-foreground-color`, so they take the foreground color of whatever block theme they sit in, rather than a color of their own.
-VLT ships `--link-foreground-color` as an opt-in: define it in your project to give links a distinct color everywhere.
+VLT declares `--link-color`, but does not use it by default.
+Instead, links use `--link-foreground-color` when it is set, and otherwise the foreground color of the block theme they sit in, `--theme-foreground-color`.
+To give links a distinct color everywhere, set `--link-foreground-color` in your project:
 
 ```scss
 :root {
@@ -125,16 +122,17 @@ VLT ships `--link-foreground-color` as an opt-in: define it in your project to g
 
 ### Block Themes
 
-VLT includes a block theme system that enables individual blocks to use distinct color palettes. These themes are configured in `config.blocks.themes` and applied through the StyleWrapper system at runtime.
+VLT includes a block theme system that lets individual blocks use their own color palette.
+The themes are configured in `config.blocks.themes`, and applied through the StyleWrapper when a block renders.
 
 **The four core block theme variables:**
 
-- `--theme-color`: Primary background color—the most visible color in the block
-- `--theme-high-contrast-color`: Secondary background color for nested elements (e.g., cards within a block) to create visual separation from the main background
-- `--theme-foreground-color`: Default text and icon color
-- `--theme-low-contrast-foreground-color`: Subdued text color for secondary content like placeholders or helper text
+- `--theme-color`: primary background color, the most visible color in the block
+- `--theme-high-contrast-color`: secondary background color for nested elements, such as cards within a block, to separate them from the main background
+- `--theme-foreground-color`: default text and icon color
+- `--theme-low-contrast-foreground-color`: subdued text color for secondary content, such as placeholders or helper text
 
-While the system can be extended with non-color CSS properties, the default four variables establish the color foundation for each theme.
+A theme can also set other CSS properties, but these four variables are the color foundation of each theme.
 
 **Example configuration:**
 
@@ -163,30 +161,34 @@ config.blocks.themes = [
 ];
 ```
 
-Users select a block theme from the **Background color** control in the block sidebar's **Styling** tab.
-VLT's `defaultStylingSchema` adds a `theme` field to the block's schema and renders it with the `color_picker` widget, which draws one button per configured theme using that theme's `--theme-color` as the button color.
+Editors select a block theme from the **Background color** control, in the **Styling** section of the block settings in the sidebar.
+VLT's `defaultStylingSchema` adds a `theme` field to the block's schema and renders it with the `color_picker` widget, which draws one swatch per configured theme, colored with that theme's `--theme-color`.
+The block stores the name of the selected theme in its `theme` field.
 
 ```{note}
-`color_picker` is a legacy name for what is really a swatch picker, and VLT registers the very same `ColorSwatch` component under both `color_picker` and `colorSwatch`.
-VLT's own source says as much, with a rename planned for Volto 19.
+`color_picker` is a legacy name for what is really a swatch picker.
+VLT registers the same `ColorSwatch` component under both `color_picker` and `colorSwatch`, and a comment in VLT's source notes that the widget should be renamed.
 
 Do not confuse it with two similarly named widgets:
 
-- `colorPicker` is a different widget entirely—a full color input with a contrast checker—used for the site-wide colors that the backend behaviors expose.
-- `themeColorSwatch` is registered by VLT but currently is not used by any schema VLT ships.
+- `colorPicker` is a different widget, a free color input with a contrast checker, used for the site-wide colors that the backend behaviors expose.
+- `themeColorSwatch` is registered by VLT, but currently no schema that VLT ships uses it.
 ```
 
 ### Container Width System
 
-VLT uses three types of container widths:
+VLT uses three container widths:
 
 ```scss
 // Three-width layout system
---layout-container-width: 1440px; // for major elements like headers & large Blocks
---default-container-width: 940px; // balanced content presentation for most Blocks
+--layout-container-width: 1440px; // for major elements like headers and large blocks
+--default-container-width: 940px; // balanced content presentation for most blocks
 --narrow-container-width: 620px; // optimal readability for text
 ```
 
+VLT declares these three custom properties from SCSS variables of the same name, such as `$default-container-width`.
+To change them, set the SCSS variables, as explained in {ref}`light-theme-custom-properties-label`.
+
 Those three are the site-wide scale. Individual blocks never read them directly. Instead, each block carries a `--block-width` property that points at one of them, and the `blockWidth` widget is what chooses the target:
 
 | Token stored | `--block-width` becomes | Resulting width |
@@ -210,6 +212,8 @@ The `blockAlignment` widget works the same way, storing one of `left`, `center`,
 --align-right: end;
 ```
 
+(light-theme-style-fields-label)=
+
 ### Style Fields and the `:noprefix` Convention
 
 Width and alignment are both **style fields**, and every style field follows the same two-step process: store a token, then resolve that token to a style object at render time.
@@ -223,7 +227,9 @@ What a block actually saves is short. A block set to narrow width and left align
 }
 ```
 
-Only the tokens are stored—no CSS, no custom property values. Resolution happens when the block renders:
+Only the tokens are stored—no CSS, no custom property values.
+This relies on the widget storing the token rather than a style object, which {ref}`the Cover block <light-theme-cover-actions-label>` in chapter 3 shows how to ensure.
+Resolution happens when the block renders:
 
 1. For each key in `styles`, VLT looks up a `styleFieldDefinition` utility registered under **that exact key**.
 2. The utility returns a list of style definitions. For `blockWidth:noprefix` that list is `config.blocks.widths`.
@@ -234,8 +240,8 @@ Storing tokens rather than values is what makes the system re-themeable. Change
 
 Separately, the StyleWrapper turns each style field into a CSS class.
 By default it prefixes the class with the field name, so a field named `align` with the value `center` produces `has--align--center`.
+A field name ending in `:noprefix` opts out of that prefixing, so `align:noprefix` with the value `center` produces the class `center`.
 
-A field name ending in `:noprefix` opts out of that prefixing.
 VLT uses this suffix for its own style fields, and registers the matching style definitions under the same literal name:
 
 ```typescript
@@ -252,39 +258,43 @@ The suffix is part of the field name, not decoration.
 A field named `align` and a field named `align:noprefix` are two different fields: only the second one matches the utility above, and only the second one gets its CSS custom properties injected.
 The three style fields VLT defines this way are `align:noprefix`, `blockWidth:noprefix`, and `size:noprefix`.
 
+(light-theme-generated-classes-label)=
 
 ### Generated Block Classes
 
-Beyond the style fields, VLT registers a set of `styleClassNameExtenders` that inspect each block's position in the page and inject extra classes on it.
+Beyond the style fields, VLT adds a set of functions to `config.settings.styleClassNameExtenders`.
+They inspect each block's position in the page and inject extra classes on it.
 This is what lets the theme control vertical spacing between blocks from CSS alone, without a block needing to know anything about its neighbors.
 
 The classes available on every block are:
 
 | Class | Injected when |
 | --- | --- |
-| `next--is--${type}` | the following block is of that type |
+| `next--is--${type}` | there is a following block, and `${type}` is its type |
 | `previous--is--same--block-type` | the preceding block has the same type |
 | `next--is--same--block-type` | the following block has the same type |
-| `is--first--of--block-type` | the preceding block has a different type |
-| `is--last--of--block-type` | the following block has a different type |
-| `has--headline` | the block has a headline, or follows a heading block |
+| `is--first--of--block-type` | the preceding block has a different type, or there is none |
+| `is--last--of--block-type` | the following block has a different type, or there is none |
+| `has--headline` | the block has a headline, or follows a Heading block |
 | `previous--has--same--backgroundColor` | the preceding block uses the same theme |
 | `next--has--same--backgroundColor` | the following block uses the same theme |
 | `previous--has--different--backgroundColor` | the preceding block uses a different theme |
 | `next--has--different--backgroundColor` | the following block uses a different theme |
-| `has--block-width--${width}` | always, from the `blockWidth:noprefix` field |
-| `has--block-alignment--${alignment}` | always, from the `align:noprefix` field |
-| `has--background-color--${theme}` | always, from the block's selected theme |
+| `has--block-width--${width}` | always, from the `blockWidth:noprefix` field, or `default` when it is empty |
+| `has--block-alignment--${alignment}` | always, from the `align:noprefix` field, or `center` when it is empty |
+| `has--background-color--${theme}` | always, from the block's theme, or `default` when it has none |
 
-You will see these used throughout VLT's own stylesheets, and in the examples later in this training.
-A typical use is collapsing the gap between two adjacent blocks that share a background, so the pair reads as one band of color:
+When VLT compares themes, a block without a theme, or a missing neighbor, counts as `default`.
+
+You will see these classes throughout VLT's own stylesheets, and in the examples later in this training.
+For example, VLT's listing styles use two of them to remove the space below a Grid listing when the next block is another listing with the same background, so the pair reads as one band of color:
 
 ```scss
-.block.listing {
+.block.listing.grid {
   &.next--has--same--backgroundColor.next--is--same--block-type {
     .listing-item:last-child {
-      padding-bottom: 0;
-      border-bottom: none;
+      padding-bottom: 0 !important;
+      border-bottom: none !important;
     }
   }
 }
@@ -294,27 +304,37 @@ Because the extenders are registered in configuration, a project can add its own
 
 ## Create a New Project with Cookieplone
 
-When creating your Plone project with **Cookieplone**, choose template **1, "Volto Project"**, then answer the prompts.
+This training uses Cookieplone 2.0 to generate the project.
+If you have not used Cookieplone before, the [Cookieplone guide](https://6.docs.plone.org/install/create-project-cookieplone.html) lists the tools it needs.
+
+From the folder where you keep your projects, run:
+
+```shell
+uvx cookieplone project
+```
+
+The `project` argument selects the **Plone 6 Project** template.
+Without it, Cookieplone first asks you to choose a category and a template.
 
-The defaults are fine for almost everything, but two answers matter for the rest of this training:
+Cookieplone then asks a series of questions.
+Accept the defaults, except for the project title:
 
-| Prompt | Default | Answer |
+| Question | Default | Answer |
 | --- | --- | --- |
-| `[1/19] Project Title` | `Project Title` | `robotarium` |
-| `[3/19] Project Slug` | `robotarium` | accept |
-| `[8/19] Plone Version` | `6.2.1` | accept |
-| `[9/19] Volto Version` | `19.4.0` | accept |
-| `[10/19] Python Package Name` | `robotarium` | accept |
-| `[11/19] Volto Addon Name` | `volto-robotarium` | **`robotarium`** |
-| everything else | | accept |
+| Project Title | `Project Title` | `Robotarium` |
+| Project Slug (Used for repository id) | `robotarium` | accept |
+| Python Package Name | `robotarium` | accept |
+| Use Volto as frontend? | Yes | accept |
+| all other questions | | accept |
 
-```{important}
-This is where the project gets its name.
-The Project Title you type at `[1/19]` becomes the project slug, the output folder, and the Python package name, and it is what every path in this training refers to.
+The title determines the other names.
+Cookieplone derives the slug `robotarium` from it, and uses the slug for the output folder and the Python package name.
+It also derives the name of the frontend add-on, `volto-robotarium`, without asking, and it picks the Plone and Volto versions for you.
+At the time of writing, it generated a project with Plone 6.2.2 and Volto 19.4.1.
 
-Pay particular attention to `[11/19] Volto Addon Name`: Cookieplone offers `volto-robotarium`, prefixed with `volto-`.
-This training uses `robotarium`, so override that default.
-If you accept the default instead, or build something other than a Robotarium, every path below of the form {file}`frontend/packages/robotarium/…` becomes {file}`frontend/packages/<your addon name>/…`.
+```{important}
+Every path in this training of the form {file}`frontend/packages/volto-robotarium/…` uses that add-on name.
+If you build something other than a Robotarium, the add-on is called `volto-` followed by your project slug, and you should adjust the paths accordingly.
 ```
 
 You should end up with this shape:
@@ -328,11 +348,9 @@ robotarium/
 └── frontend/
     ├── mrs.developer.json
     ├── volto.config.js
-    └── packages/robotarium/     <- your project add-on
+    └── packages/volto-robotarium/     <- your project add-on
 ```
 
-For more detail, see the [Cookieplone guide](https://6.docs.plone.org/install/create-project-cookieplone.html).
-
 ## Installing Volto Light Theme
 
 VLT is shipped as two add-ons that you must install together:
@@ -341,61 +359,51 @@ VLT is shipped as two add-ons that you must install together:
 - the backend Plone add-on `kitconcept.voltolighttheme`, which provides the site customization behaviors.
 
 ```{note}
-This training targets the VLT 8 line, which is currently released as alpha (`8.0.0-alpha.x` on npm, `8.0.0a.x` on PyPI), and is the version documented in the [official VLT install guide](https://volto-light-theme.readthedocs.io/how-to-guides/install.html).
-If you need a stable release instead, use the latest 7.x version of both packages and skip the "install the recommended add-ons as dependencies" step, since 7.x still ships them as `peerDependencies`.
-```
-
-### Step 1: Install VLT and Recommended Block Add-ons
-
-VLT is installed like any other Volto add-on, as a dependency of your project add-on in {file}`frontend/packages/robotarium/package.json`:
-
-```json
-{
-  "dependencies": {
-    "@kitconcept/volto-light-theme": "^8.0.0-alpha.31"
-  }
-}
+This training uses VLT 8.0.0, which requires Volto 19.
+The [VLT compatibility table](https://volto-light-theme.readthedocs.io/reference/compatibility.html) lists the Volto versions that each VLT version supports.
 ```
 
-From the root of your project, you can let pnpm add it to the workspace package for you:
+You first declare both add-ons in your project, and then install everything with a single command.
 
-```bash
-pnpm --filter robotarium add @kitconcept/volto-light-theme@alpha
-```
+### Step 1: Declare the Frontend Packages
 
-Volto Light Theme supports all core blocks, and it also supports blocks coming from a set of recommended add-ons that provide the basic blocks for your website.
+VLT supports all core blocks, and it also supports blocks from a set of recommended add-ons that provide the basic blocks for your website.
 Including them is not required, and you can pick only the ones you want to use.
 
-Since VLT 8.0.0, these recommended add-ons are no longer declared as `peerDependencies` of VLT, so you have to install them yourself as dependencies of your project add-on in {file}`frontend/packages/robotarium/package.json`:
+VLT does not install the recommended block add-ons for you, so you add them to your project add-on yourself, together with VLT.
+Open {file}`frontend/packages/volto-robotarium/package.json` and add them to its `dependencies`:
 
 ```json
 {
   "dependencies": {
     "@eeacms/volto-accordion-block": "^12.0.0",
-    "@kitconcept/volto-banner-block": "^1.2.0",
+    "@kitconcept/volto-banner-block": "^1.2.1",
     "@kitconcept/volto-bm3-compat": "^1.0.0-alpha.1",
-    "@kitconcept/volto-button-block": "5.0.0-alpha.2",
-    "@kitconcept/volto-calendar-block": "^1.0.0-alpha.9",
-    "@kitconcept/volto-carousel-block": "^3.0.0-alpha.1",
-    "@kitconcept/volto-dsgvo-banner": "^4.0.0-alpha.2",
+    "@kitconcept/volto-button-block": "^5.0.0",
+    "@kitconcept/volto-carousel-block": "^3.0.0",
+    "@kitconcept/volto-dsgvo-banner": "^4.0.0",
     "@kitconcept/volto-heading-block": "^2.5.0",
-    "@kitconcept/volto-highlight-block": "^5.0.0-alpha.2",
+    "@kitconcept/volto-highlight-block": "^5.0.0",
     "@kitconcept/volto-introduction-block": "^1.4.1",
-    "@kitconcept/volto-logos-block": "^4.0.0-alpha.1",
-    "@kitconcept/volto-separator-block": "^5.0.0-alpha.0",
-    "@kitconcept/volto-slider-block": "^7.0.0-alpha.1",
-    "@plonegovbr/volto-social-media": "^3.0.0-alpha.0",
-    "@kitconcept/volto-light-theme": "^8.0.0-alpha.31"
+    "@kitconcept/volto-light-theme": "^8.0.0",
+    "@kitconcept/volto-logos-block": "^4.0.0",
+    "@kitconcept/volto-separator-block": "^5.0.0",
+    "@kitconcept/volto-slider-block": "^7.0.0",
+    "@plonegovbr/volto-social-media": "^3.0.0-alpha.0"
   }
 }
 ```
 
 ```{note}
-The versions above are the known good versions at the time of writing.
-The source of truth, up-to-date list lives in the [recommended add-ons reference](https://volto-light-theme.readthedocs.io/reference/recommended-addons.html) of the VLT documentation.
+These are the known good versions for VLT 8.0.0. The up-to-date list lives in the [recommended add-ons reference](https://volto-light-theme.readthedocs.io/reference/recommended-addons.html) of the VLT documentation.
 ```
 
-Installing a package is not enough: it also has to be declared as a Volto add-on in the `addons` key of the same {file}`package.json`, with VLT as the last element of the list:
+`@kitconcept/volto-bm3-compat` is not a block add-on.
+VLT already depends on it, and you list it here because the block you build in chapter 3 imports from it.
+
+Installing a package is not enough: Volto also has to load it as an add-on.
+In the same {file}`package.json`, Cookieplone generated two empty keys, `"addons": []` and `"theme": ""`.
+List the add-ons in `addons`, and declare VLT as the `theme`:
 
 ```json
 {
@@ -414,77 +422,51 @@ Installing a package is not enough: it also has to be declared as a Volto add-on
     "@kitconcept/volto-slider-block",
     "@plonegovbr/volto-social-media",
     "@kitconcept/volto-light-theme"
-  ]
-}
-```
-
--**Important:** VLT must be the last addon in the list to ensure proper style cascade. Your project addon will still be the last applied if defined in `volto.config.js`.
-
-Don't install anything yet.
-The backend needs an edit too, and a single command at the end installs both—see {ref}`vlt-install-step-3`.
-
-### Step 2: Configure VLT as the Theme Provider
-
-VLT is not only a regular add-on, it is also a theme add-on, so it has to be declared as the theme of your project.
-How you do that depends on your Volto version.
-
-For Volto 18.29.1 or later, and 19.0.0-alpha.10 or later, declare it with the `theme` key of your project add-on {file}`frontend/packages/robotarium/package.json`, next to the `addons` key:
-
-```json
-{
-  "addons": [
-    ...,
-    "@kitconcept/volto-light-theme"
   ],
   "theme": "@kitconcept/volto-light-theme"
 }
 ```
 
-Cookieplone already generates both keys for you, as `"addons": []` and `"theme": ""`, so this is an edit rather than something you add from scratch.
-
-For older Volto versions, open the {file}`volto.config.js` file in your `frontend` folder and declare the theme there instead:
+VLT needs both keys, because it is both a regular add-on and a theme add-on.
 
-```javascript
-const addons = ["robotarium"];
-const theme = "@kitconcept/volto-light-theme";
+```{important}
+VLT must be the last entry in `addons`.
+Volto applies add-ons in the order you list them, and VLT's configuration extends the blocks that the other add-ons register, so it has to run after theirs.
 
-module.exports = {
-  addons,
-  theme,
-};
+Your project add-on is applied after all of them, because Volto applies the add-ons that an add-on declares before the add-on itself.
 ```
 
-You'll need to restart your Plone frontend to see the changes.
-
-That's it! Your project should now be using Volto Light Theme with its additional blocks and components.
-
-(vlt-install-step-3)=
-
-### Step 3: Add the Backend Package and Install Everything
+### Step 2: Declare the Python Package
 
-Edit {file}`backend/pyproject.toml` and add `kitconcept.voltolighttheme` to the dependencies array:
+Edit {file}`backend/pyproject.toml` and add `kitconcept.voltolighttheme` to the `dependencies` array that Cookieplone generated:
 
 ```toml
 dependencies = [
-    "Products.CMFPlone==6.2.1",
+    "Products.CMFPlone==6.2.2",
     "plone.api",
     "plone.restapi",
     "plone.volto",
-    "kitconcept.voltolighttheme==8.0.0a31",
+    "kitconcept.voltolighttheme==8.0.0",
 ]
 ```
 
+Keep the Plone version that Cookieplone generated for you, if it differs from the one shown here.
+
+### Step 3: Install Everything
+
 Both manifests are now edited, so install the whole project in one step, from the project root:
 
-```bash
+```shell
 make install
 ```
 
-### Step 4: Start the Servers and Install the Backend Add-on
+This installs the backend and the frontend, and creates a Plone site with the id `Plone`.
+
+### Step 4: Start the Servers and Install VLT in Plone
 
 Start your development environment, from the project root, in two terminals:
 
-```bash
+```shell
 # Terminal 1 - Backend
 make backend-start
 
@@ -492,37 +474,68 @@ make backend-start
 make frontend-start
 ```
 
-Once the frontend is running:
+Once the frontend is running, open http://localhost:3000.
+The first time you open the site, a cookie consent dialog from `@kitconcept/volto-dsgvo-banner` covers the page.
+Choose one of its options to close it.
+
+Then log in at http://localhost:3000/login with the user `admin` and the password `admin`, and install the backend add-on:
 
-1. Go to http://localhost:3000/controlpanel/addons
-2. Find "Volto Light Theme" in the list
-3. Click "Install"
+1. Go to http://localhost:3000/controlpanel/addons.
+2. In the list of available add-ons, select **Volto Light Theme: Install** to show its details.
+3. Select **Install**.
 
 ### Step 5: Activate Behaviors for Plone Site
 
-The backend add-on ships five behaviors. None of them is enabled automatically, because each one adds fields to the Plone Site edit form and you should opt into the ones you want.
+The backend add-on ships five behaviors.
+None of them is enabled automatically, because each one adds fields to the edit form of the content type you apply it to, and you should opt into the ones you want.
 
 | Behavior | Shown in the Behaviors tab as | What it adds |
 | --- | --- | --- |
-| `voltolighttheme.header` | Header customizations for sites/subsites | Site logo, complementary logo, fat menu toggle, intranet header, header actions |
-| `voltolighttheme.theme` | Theme colors customizations for sites/subsites | Five color fields for the navigation, fat menu, and footer—see below |
-| `voltolighttheme.footer` | Footer customizations for sites/subsites | Footer links, footer logos and their size, colophon text |
-| `kitconcept.footer` | kitconcept specific footer customizations | The additional footer arrangement used by kitconcept distributions |
-| `kitconcept.sticky_menu` | Sticky menu | A menu fixed to the right side of the screen |
+| `voltolighttheme.header` | Header customizations for sites/subsites | Site logo, complementary logo, fat menu switch, intranet header switch, site flag, and site actions |
+| `voltolighttheme.theme` | Theme colors customizations for sites/subsites | Five color fields for the navigation, fat menu, breadcrumbs, and footer. See {ref}`light-theme-behavior-colors-label`. |
+| `voltolighttheme.footer` | Footer customizations for sites/subsites | Footer logos with their size and container width, footer links, and the footer colophon text |
+| `kitconcept.footer` | kitconcept specific footer customizations | The footer layout of kitconcept distributions: a footer logo, an address, three link columns, and a sponsor logo with its link |
+| `kitconcept.sticky_menu` | Sticky menu | Icon links fixed to the right edge of the screen, their colors, and a switch to show them on mobile |
+
+The header fields work as follows:
+
+Site logo
+:   The main logo, at the top left of the header.
+
+Complementary logo
+:   A second logo on the right side of the header. Only the intranet header shows it.
+
+Fat menu switch
+:   The fat menu is the panel that opens below the navigation when you select a main section. It is enabled by default.
 
-To activate them:
+Intranet header switch
+:   Replaces the default header with a layout intended for intranet sites.
 
-1. Go to http://localhost:3000/controlpanel/dexterity-types/Plone%20Site
-2. In the "Behaviors" tab, tick the behaviors from the table above that you want
-3. Click "Save"
+Site flag
+:   A short text shown in a colored pill at the top of the header.
 
-The first three are the ones this training uses. Enable all five if you want to see everything the add-on offers.
+Site actions
+:   Links shown at the top right of the header, each with a title, a target URL, and an option to open it in a new tab.
 
-These behaviors put the knobs on the content type they are applied to, so applying them to the Plone Site configures the whole site, and applying them to a subsite configures that branch instead.
+To activate the behaviors:
 
-#### What the theme behavior actually does
+1. Go to http://localhost:3000/controlpanel/dexterity-types/Plone%20Site.
+2. In the **Behaviors** tab, select the behaviors from the table above that you want.
+3. Select **Save**.
 
-The behavior adds five empty, optional fields to the edit form, each rendered with the `colorPicker` widget:
+This training uses the first three.
+Leave `kitconcept.footer` disabled while you follow it: when it is active, VLT renders kitconcept's footer layout, which sets its own footer background colors and replaces the footer gradient that you define in the next chapter.
+
+The behaviors add their fields to the content type they are applied to.
+Applied to the Plone Site, they configure the whole site.
+Applied to a subsite, they configure that branch instead, and each page uses the settings of its nearest ancestor that has them.
+
+(light-theme-behavior-colors-label)=
+
+#### What the theme behavior does
+
+The behavior adds five empty, optional fields to the **Theming** tab of the edit form, each rendered with the `colorPicker` widget.
+When an editor fills in a field, VLT sets the matching custom property:
 
 | Field | Label in the form | Custom property it sets |
 | --- | --- | --- |
@@ -532,55 +545,64 @@ The behavior adds five empty, optional fields to the edit form, each rendered wi
 | `secondary_foreground_color` | Footer Font Color | `--secondary-foreground-color` |
 | `secondary_color` | Footer Background Color | `--secondary-color` |
 
-Note that there is no primary color pair here: `primary_color` exists in VLT's frontend color map but is deliberately commented out of the behavior's fieldset.
+There is no field for the primary color pair.
+The header background follows `--primary-color`, which no field of the behavior sets, and the navigation text color has its own field, `header_foreground`.
+
+VLT writes the values that editors choose into a `:root` rule at the top of the document head.
+Your project's stylesheet comes after that rule, and the design tokens that you will define in the next chapter use the same `:root` selector.
+When both set the same property, your stylesheet wins, and the value that the editor chose has no effect.
 
 ```{important}
-Those declarations land in `:root` from a tag in the document head, at the same specificity as the design tokens you will define in the next chapter.
-If you set `--accent-color` in your project's stylesheet **and** an editor fills in Fat Menu Background Color, the editor's value is the one that applies.
-That is the intended division of labour—the behaviors exist so that editors can override the theme—but it does mean these five properties are not yours to fix from CSS once the behavior is active.
+Decide who owns each of these five properties.
+If editors should be able to change a color, leave its property out of your stylesheet.
+
+The Robotarium's stylesheet sets `--accent-color`, `--accent-foreground-color`, and `--secondary-color` in the next chapter.
+On the Robotarium, the Fat Menu Background Color, Fat Menu / Breadcrumbs Text Color, and Footer Background Color fields therefore have no effect, while Navigation Text Color and Footer Font Color still work.
 ```
 
 ```{note}
-Behaviors can be added in new releases, and this table reflects `kitconcept.voltolighttheme` 8.0.0a31.
+Behaviors can be added in new releases, and this table reflects `kitconcept.voltolighttheme` 8.0.0.
 The authoritative list is the behavior registration in the add-on itself, at {file}`backend/src/kitconcept/voltolighttheme/behaviors/configure.zcml` in the [VLT repository](https://github.com/kitconcept/volto-light-theme).
 See the [site customization guide](https://volto-light-theme.readthedocs.io/conceptual-guides/site-customization.html) for what each field does.
 ```
 
-Now your project should have the VLT Site configurations available.
+Your site now has the VLT site customization fields available.
 
 ## File Structure Setup
 
-Let's set up the recommended file structure in your project add-on's `src` folder.
-Cookieplone already gave you some of it—`index.ts` and `config/settings.ts` exist and have content, so you are filling in the gaps rather than starting from nothing:
+Set up the recommended file structure in your project add-on's `src` folder.
+Cookieplone already created part of it, so you are filling in the gaps rather than starting from nothing:
 
 ```console
 src/
-├── components/
+├── components/          # exists, empty
 │   └── blocks/          # new
 ├── config/
-│   ├── settings.ts      # exists, generated with your language settings
+│   ├── settings.ts      # exists, sets the default language
 │   └── blocks.ts        # new
-├── index.ts             # exists, generated with applyConfig()
+├── index.ts             # exists, calls installSettings()
 └── theme/               # new
     ├── blocks/
     ├── _variables.scss
     └── _main.scss
 ```
 
-From {file}`frontend/packages/robotarium/src`:
+From {file}`frontend/packages/volto-robotarium/src`:
 
-```bash
+```shell
 mkdir -p components/blocks config theme/blocks
 touch config/blocks.ts theme/_variables.scss theme/_main.scss
 ```
 
 ```{warning}
 Do not overwrite the generated {file}`index.ts` and {file}`config/settings.ts`.
-The generated `settings.ts` holds your `isMultilingual`, `supportedLanguages`, and `defaultLanguage` values, and `index.ts` already wires it up.
+The generated `settings.ts` sets your site's `defaultLanguage`, and `index.ts` already calls it.
 Every later step in this training that shows one of these two files is showing an **edit**, not a replacement.
 ```
 
-Remember that if you add new files to your project, it will be necessary to restart your Plone frontend.
+Whenever you add new files to your project, restart the frontend, because hot reload does not pick them up.
+
+(light-theme-insertion-points-label)=
 
 ### The Two Theme Insertion Points
 
@@ -593,40 +615,41 @@ Volto scans every add-on for {file}`theme/_variables.scss` and {file}`theme/_mai
 | {file}`theme/_main.scss` | **after** all of VLT's styles | everything else, including all your custom properties |
 
 The order is what makes each one useful.
-No other filename is special—`theme/blocks/` and anything else you add are ordinary partials that become part of the build only because {file}`_main.scss` imports them.
+No other filename is special: `theme/blocks/` and anything else you add are ordinary partials that become part of the build only because {file}`_main.scss` imports them.
 
 ```{note}
 Volto skips these two files for whichever add-on is registered as the `theme`.
-They work for {file}`robotarium` precisely because VLT, not your project, is the theme add-on.
+They work for {file}`volto-robotarium` precisely because VLT, not your project, is the theme add-on.
 ```
 
+(light-theme-custom-properties-label)=
+
 #### Prefer CSS custom properties
 
 Almost all of your theming should be CSS custom properties written in {file}`_main.scss`, not SCSS variables.
 
-VLT is built as a custom-property system: the color pairs, the semantic properties, the container widths, and the block themes are all custom properties, resolved in the browser. That is what makes them overridable per block, per section, and at runtime—a block theme works by re-declaring `--theme-color` on one block, which no build-time variable could do. Setting your design tokens as custom properties in `:root` is the normal path, and it is what the next chapter does:
+VLT is built as a custom-property system: the color pairs, the semantic properties, the container widths, and the block themes are all custom properties, resolved in the browser. That is what lets you override them per block, per section, and at runtime—a block theme works by re-declaring `--theme-color` on one block, which no build-time variable could do. Setting your design tokens as custom properties in `:root` is the normal path, and the next chapter sets these, among others:
 
 ```scss
 // src/theme/_main.scss
 :root {
-  --primary-color: #10131a;
-  --accent-color: #d8f24e;
-  --link-color: #2f5fd8;
+  --accent-color: #3b5759;
+  --accent-foreground-color: #fff;
+  --link-foreground-color: #157a7a;
 }
 ```
 
-{file}`_variables.scss` is the narrow exception, for values VLT **computes with at build time**. VLT declares its SCSS variables with `!default`, so each one applies only when nothing has already set it. Since {file}`_variables.scss` is injected first, anything you assign there wins—and it is the *only* place they can be changed, because by the time {file}`_main.scss` is injected, VLT's stylesheets have already been compiled:
+{file}`_variables.scss` is the narrow exception, for values VLT **computes with at build time**. VLT declares its SCSS variables with `!default`, so each one applies only when nothing has already set it. Since {file}`_variables.scss` is injected first, anything you assign there wins—and it is the *only* place they can be changed, because VLT's stylesheets have already used the values by the time {file}`_main.scss` is injected:
 
 ```scss
 // src/theme/_variables.scss
-$tablet-breakpoint: 900px;
 $default-container-width: 1120px;
 ```
 
 Two kinds of value belong there:
 
 - **Breakpoints**, which cannot be custom properties at all, since media queries cannot read them.
-- **The container widths**, which are subtler and worth understanding.
+- **The three container widths.** VLT declares `--layout-container-width`, `--default-container-width`, and `--narrow-container-width` from the SCSS variables of the same name, and also uses the SCSS values in media and container queries. Setting the SCSS variable updates both, so you never set the custom property yourself.
 
 The rule of thumb: custom properties for anything meant to vary per block, per section, or at runtime—which is nearly everything, and all of the color system. SCSS variables only for the handful of values VLT compiles into media queries and mixins.
 
@@ -634,10 +657,10 @@ The rule of thumb: custom properties for anything meant to vary per block, per s
 
 Restart both servers and confirm the install landed before moving on. Most trouble in later chapters traces back to one of these:
 
-- The site at http://localhost:3000 renders in VLT's styling, not Volto's default Pastanaga theme. If it looks unchanged, VLT is registered as an add-on but not as the `theme`.
-- Editing a page and selecting a block shows a **Background color** control in the sidebar's **Styling** tab. This confirms VLT's block configuration is applied.
-- The add-ons control panel lists **Volto Light Theme** as installed, and the Plone Site content type shows the `voltolighttheme` behaviors as active.
-- Adding an empty {file}`src/theme/_main.scss` with a single obvious rule, such as `body { border-top: 4px solid red; }`, actually shows that border. If it does not, your add-on is not being picked up as a theme add-on, and no amount of CSS in later chapters will apply.
+- The site at http://localhost:3000 renders in VLT's styling, not Volto's default Pastanaga theme. If it looks unchanged, VLT is listed in `addons` but not declared as the `theme`.
+- Editing a page and selecting a Text block shows a **Background color** control in the **Styling** section of the block settings. This confirms VLT's block configuration is applied.
+- The add-ons control panel lists **Volto Light Theme: Install** among the installed add-ons, and the Plone Site content type shows the `voltolighttheme` behaviors as enabled.
+- Adding a temporary rule to {file}`src/theme/_main.scss`, such as `body { border-top: 4px solid red; }`, shows that border after a restart. If it does not, your add-on is not being picked up, and no amount of CSS in later chapters will apply. Remove the rule afterward.
 
 ## Further Reading
 
@@ -647,3 +670,4 @@ This training covers the parts of VLT you need to build a project. The theme's o
 - [Layout](https://volto-light-theme.readthedocs.io/conceptual-guides/layout.html)
 - [Vertical spacing](https://volto-light-theme.readthedocs.io/conceptual-guides/vertical-spacing.html)
 - [Install guide](https://volto-light-theme.readthedocs.io/how-to-guides/install.html)
+- [Site customization](https://volto-light-theme.readthedocs.io/conceptual-guides/site-customization.html)
diff --git a/docs/customizing-volto-light-theme/design-system-implementation.md b/docs/customizing-volto-light-theme/design-system-implementation.md
index 643b98ae6..564ea9c6b 100644
--- a/docs/customizing-volto-light-theme/design-system-implementation.md
+++ b/docs/customizing-volto-light-theme/design-system-implementation.md
@@ -9,65 +9,46 @@ myst:
 
 # Design System Implementation & Theming
 
-The Robotarium has a look: workshop teal, a technical typeface, and surfaces that read like painted metal. This chapter turns that into a working theme.
+The Robotarium has a look: workshop teal, a technical font, and surfaces that read like painted metal. This chapter turns that into a working theme.
 
 Nothing here is specific to robots. The steps are the ones you follow for any design handed to you—pull the decisions out of it, express them as tokens, and let VLT's components pick them up.
 
 ## Extracting Design Tokens
 
-When working with a given design, systematically extract design decisions. Identify:
+Before writing any code, list the decisions that the design makes:
 
-### Color Extraction Checklist
-
-1. **Primary Colors**
-   - Background color
-   - Text color on primary
-
-2. **Secondary Colors**
-   - Background color
-   - Text color on secondary
-
-3. **Accent Colors**
-   - Highlight color
-   - Text color on accent
-
-4. **Semantic Colors**
-   - Link colors
-
-### Typography Extraction
-
-Look for:
-- Font families
-- Line heights
-- Font weights
+- **Color pairs**: the primary, secondary, and accent background colors, and the text color used on each.
+- **Link color**, if links should stand out from the surrounding text.
+- **Typography**: the font families, and any line heights or font weights that differ from VLT's.
+- **Block palettes**: the backgrounds that editors should be able to choose for a section of a page.
 
+For the Robotarium, that list comes down to a dark teal accent with white text, a pale teal secondary color, a teal link color, the Chakra Petch font, and one extra block palette.
 
 ## Implementing Your Design System
 
-VLT has migrated to use standardized color definitions. These use CSS properties that are injected at runtime in the right places, so your CSS can adapt to use them generically. The resulting CSS is simpler, and there's no need to define class names for each color definition.
-
 ### Step 1: Add Font Files
 
 If you're using custom fonts, add the font files to your theme directory.
-The Robotarium uses [Chakra Petch](https://fonts.google.com/specimen/Chakra+Petch); from {file}`frontend/packages/robotarium/src/theme`:
+The Robotarium uses [Chakra Petch](https://fonts.google.com/specimen/Chakra+Petch).
+From {file}`frontend/packages/volto-robotarium/src/theme`, create a folder for it:
 
-```bash
+```shell
 mkdir -p fonts/Chakra_Petch
 ```
 
-at the end, it should look like:
+Download the font family from Google Fonts, and copy its regular and bold files into that folder:
 
-```
+```console
 src/theme/fonts/Chakra_Petch/
-  ├── ChakraPetch-Regular.ttf
-  └── ChakraPetch-Bold.ttf
+├── ChakraPetch-Regular.ttf
+└── ChakraPetch-Bold.ttf
 ```
 
-This ensures the font files are bundled with your theme and can be referenced in your SCSS files.
+Keeping the files inside your theme bundles them with it, so your stylesheets can refer to them with relative paths.
 
 ### Step 2: Override SCSS Variables
 
-Some of VLT's design decisions are SCSS variables rather than CSS custom properties. Those belong in {file}`src/theme/_variables.scss`:
+Set the build-time values in {file}`src/theme/_variables.scss`, as described in {ref}`light-theme-custom-properties-label`:
 
 ```scss
 // src/theme/_variables.scss
@@ -75,8 +56,8 @@ $default-container-width: 1120px;
 $spacing-large: 80px;
 ```
 
-VLT declares its variables with `!default`, so whatever you assign here wins.
-It also derives the matching CSS custom properties from them, which means setting `$default-container-width` here updates `--default-container-width` too. You do not need to set both.
+The Robotarium widens the default container from 940px to 1120px, and increases VLT's large spacing step from 60px to 80px.
+Setting `$default-container-width` also updates `--default-container-width`, so you do not need to set both.
 
 ### Step 3: Define Your Design Tokens
 
@@ -112,20 +93,21 @@ In {file}`src/theme/_main.scss`, declare the fonts and the CSS custom properties
   // Give links a color of their own instead of the theme foreground color
   --link-foreground-color: #157a7a;
 
-  // Breadcrumbs
-  --breadcrumbs-background: var(--background, #fff);
-  --breadcrumbs-foreground: var(--secondary-foreground-color, #3b5759);
+  // Breadcrumbs: a white bar, with text in the footer text color
+  --breadcrumbs-background: var(--background);
+  --breadcrumbs-foreground: var(--secondary-foreground-color);
 
-  // Gradients for header and footer
+  // Gradients for header and footer.
+  // `--background` is VLT's base color, white by default.
   --header-background: linear-gradient(
     -3deg,
-    var(--background, #fff) 0%,
-    color-mix(in oklab, var(--secondary-color) 1%, var(--background, #fff)) 20%,
-    color-mix(in oklab, var(--secondary-color) 3%, var(--background, #fff)) 35%,
-    color-mix(in oklab, var(--secondary-color) 10%, var(--background, #fff)) 50%,
-    color-mix(in oklab, var(--secondary-color) 30%, var(--background, #fff)) 65%,
-    color-mix(in oklab, var(--secondary-color) 65%, var(--background, #fff)) 80%,
-    color-mix(in oklab, var(--secondary-color) 90%, var(--background, #fff)) 92%,
+    var(--background) 0%,
+    color-mix(in oklab, var(--secondary-color) 1%, var(--background)) 20%,
+    color-mix(in oklab, var(--secondary-color) 3%, var(--background)) 35%,
+    color-mix(in oklab, var(--secondary-color) 10%, var(--background)) 50%,
+    color-mix(in oklab, var(--secondary-color) 30%, var(--background)) 65%,
+    color-mix(in oklab, var(--secondary-color) 65%, var(--background)) 80%,
+    color-mix(in oklab, var(--secondary-color) 90%, var(--background)) 92%,
     var(--secondary-color) 100%
   );
 
@@ -133,24 +115,26 @@ In {file}`src/theme/_main.scss`, declare the fonts and the CSS custom properties
     ellipse 100% 100% at 50% 100%,
     var(--secondary-color) 0%,
     var(--secondary-color) 20%,
-    color-mix(in oklab, var(--secondary-color) 85%, var(--background, #fff)) 30%,
-    color-mix(in oklab, var(--secondary-color) 65%, var(--background, #fff)) 40%,
-    color-mix(in oklab, var(--secondary-color) 45%, var(--background, #fff)) 50%,
-    color-mix(in oklab, var(--secondary-color) 30%, var(--background, #fff)) 60%,
-    color-mix(in oklab, var(--secondary-color) 18%, var(--background, #fff)) 70%,
-    color-mix(in oklab, var(--secondary-color) 10%, var(--background, #fff)) 80%,
-    color-mix(in oklab, var(--secondary-color) 4%, var(--background, #fff)) 90%,
-    var(--background, #fff) 100%
+    color-mix(in oklab, var(--secondary-color) 85%, var(--background)) 30%,
+    color-mix(in oklab, var(--secondary-color) 65%, var(--background)) 40%,
+    color-mix(in oklab, var(--secondary-color) 45%, var(--background)) 50%,
+    color-mix(in oklab, var(--secondary-color) 30%, var(--background)) 60%,
+    color-mix(in oklab, var(--secondary-color) 18%, var(--background)) 70%,
+    color-mix(in oklab, var(--secondary-color) 10%, var(--background)) 80%,
+    color-mix(in oklab, var(--secondary-color) 4%, var(--background)) 90%,
+    var(--background) 100%
   );
-
-  --fatmenu-foreground: #fff;
 }
 ```
 
-Notice that the header and footer gradients are assigned to the same `--header-background` and `--footer-background` properties you saw in the previous chapter.
-Because VLT reads those properties rather than hard-coded colors, a gradient works everywhere a flat color would, with no component changes.
+The breadcrumbs tokens replace VLT's defaults, which use the accent colors.
+The Robotarium's accent text color is white, for the teal fat menu, and it would disappear on the white breadcrumbs bar, so the breadcrumbs take the text color of the footer instead.
+As a result, the Footer Font Color field of the theme behavior also changes the color of the breadcrumbs.
+
+The header and footer gradients are assigned to the same `--header-background` and `--footer-background` properties you saw in the previous chapter.
+VLT paints the header and the footer with `background`, not `background-color`, so a gradient works there as well as a flat color, with no component changes.
 
-Setting a font is a good example of the "prefer custom properties" rule from the previous chapter: you do not shadow VLT's typography stylesheets, you set the one property they already read.
+Setting a font is a good example of the {ref}`prefer custom properties <light-theme-custom-properties-label>` rule from the previous chapter: you do not shadow VLT's typography stylesheets, you set the one property they already read.
 
 Site-wide rules that are not tokens go in the same file, outside `:root`:
 
@@ -167,13 +151,6 @@ Site-wide rules that are not tokens go in the same file, outside `:root`:
     padding-top: 0;
   }
 }
-
-// Match the theme swatch in the sidebar to the custom "charging bay" theme
-#sidebar {
-  .color-swatch-widget .color-swatch-option-handler.charging-bay {
-    background: linear-gradient(135deg, var(--secondary-color) 0%, #fff 100%);
-  }
-}
 ```
 
 ```{warning}
@@ -184,8 +161,10 @@ Nesting a selector such as `#page-document` inside `:root` compiles to `:root #p
 ### Step 4: Add Block-Specific Styles
 
 Keep per-block styles in their own partials under {file}`src/theme/blocks/`, one file per block.
-This keeps them easy to find and stops {file}`_main.scss` from turning too complex.
+This keeps them easy to find, and stops {file}`_main.scss` from growing too large.
+The Robotarium adds four of them.
 
+The button partial replaces the colors of buttons on hover and focus with the accent colors:
 
 ```scss
 // src/theme/blocks/_button.scss
@@ -210,6 +189,16 @@ body .block.__button {
 }
 ```
 
+VLT colors buttons inside themed blocks with rules that start with `body`.
+Starting your rule with `body` as well gives it the same specificity, and it wins because your stylesheet loads after VLT's.
+
+The hover colors also matter for the gradient palette that you add in Step 5.
+VLT's own hover state uses `--theme-color` as the text color.
+A gradient is not a valid text color, so in a section with a gradient palette, the button text would inherit the dark foreground color and disappear against the dark hover background.
+The accent colors avoid that.
+
+The slider and grid partials give text a frosted-glass panel, on the slide titles and in four-column grids:
+
 ```scss
 // src/theme/blocks/_slider.scss
 .block.slider .teaser-item .teaser-item-title {
@@ -234,6 +223,8 @@ body .block.__button {
 }
 ```
 
+The teaser partial adds space around the text of Teaser blocks:
+
 ```scss
 // src/theme/blocks/_teaser.scss
 .block.teaser .card .card-inner .card-summary {
@@ -241,8 +232,8 @@ body .block.__button {
 }
 ```
 
-The teaser rule uses `$spacing-large`, one of VLT's SCSS variables.
-Those are in scope for your stylesheets because {file}`_main.scss` is compiled after VLT's variables and mixins, so you can reuse the theme's spacing scale, breakpoints, and typography mixins instead of inventing new values.
+The teaser rule uses `$spacing-large`, one of VLT's SCSS variables, which you set to 80px in Step 2.
+VLT's variables and mixins are in scope for your stylesheets because {file}`_main.scss` is compiled after them, so you can reuse the theme's spacing scale, breakpoints, and typography mixins instead of inventing new values.
 
 (charging-bay-label)=
 
@@ -250,7 +241,7 @@ Those are in scope for your stylesheets because {file}`_main.scss` is compiled a
 
 Block themes are the palettes an editor can choose between on any block. The Robotarium gets two: the plain default, and **Charging Bay**, a soft teal wash for sections that should feel like the lit alcove where the robots dock.
 
-In `src/config/blocks.ts`, define them:
+In {file}`src/config/blocks.ts`, define them:
 
 ```typescript
 import type { ConfigType } from '@plone/registry';
@@ -294,23 +285,47 @@ export default function install(config: ConfigType) {
 ```
 
 ```{note}
-The Grid block is the only block in VLT—or in any of the recommended add-ons—that keeps its own copy of the palettes, so this is the only place the extra line is needed.
+VLT copies the default palettes to the Grid block when its own configuration runs, which is before yours.
+The Grid block is the only block in VLT, or in any of the recommended add-ons, that keeps its own copy of the palettes, so this is the only place where the extra line is needed.
+```
+
+(light-theme-gradient-themes-label)=
+
+```{warning}
+`--theme-color` is usually a flat color, but Charging Bay sets it to a gradient.
+A gradient only works where a stylesheet reads the property with `background`, as VLT does for block backgrounds.
+Where a stylesheet reads it with `background-color` or `color`, the browser ignores the declaration:
+
+- The Charging Bay swatch in the block settings would look empty, which the rule below fixes.
+- The Button block would lose its hover text color, which the button partial from Step 4 fixes.
+
+In your own styles, read `--theme-color` with `background`, never with `background-color`.
+```
+
+VLT styles the swatches in the **Background color** control with `background-color: var(--theme-color)`.
+Add this rule to {file}`src/theme/_main.scss`, next to the other site-wide rules, to give the Charging Bay swatch a gradient of its own:
+
+```scss
+// Match the theme swatch in the sidebar to the custom "charging bay" theme
+#sidebar {
+  .color-swatch-widget .color-swatch-option-handler.charging-bay {
+    background: linear-gradient(135deg, var(--secondary-color) 0%, #fff 100%);
+  }
+}
 ```
 
 ### Step 6: Keep the Layout Settings in Sync
 
 Widening the container in SCSS is only half the change.
 VLT also reads the container width from configuration, in {file}`src/config/settings.ts`.
-Add the `layout` block to the file Cookieplone generated—do not replace it, or you will drop your language settings:
+Add the `layout` block to the file that Cookieplone generated.
+Do not replace the file, or you will drop your language settings:
 
 ```typescript
 import type { ConfigType } from '@plone/registry';
 
 export default function install(config: ConfigType) {
-  // Language settings (generated — keep these)
-  config.settings.isMultilingual = false;
-  config.settings.supportedLanguages = ['en'];
-  config.settings.defaultLanguage = 'en';
+  // ... the language settings generated by Cookieplone ...
 
   // Added in this step
   config.settings.layout = {
@@ -322,14 +337,16 @@ export default function install(config: ConfigType) {
 }
 ```
 
-This value is not used for layout—the CSS custom property does that. It is used to compute the `sizes` attribute of responsive images in teasers and listings, which tells the browser how wide an image will actually be so it can pick the right scale to download.
+This value is not used for layout—the CSS custom property does that.
+It is used to compute the `sizes` attribute of responsive images in teasers and listings, which tells the browser how wide an image will actually be, so that it can pick the right scale to download.
 
-If the two disagree, nothing breaks visibly, but the browser makes its choice from the wrong number and downloads scales that are too small, so images look soft.
+If the two values disagree, nothing breaks visibly, but the browser picks image scales for the wrong width.
+When the configured width is too small, images look soft; when it is too large, pages download bigger images than they need.
 Whenever you change `$default-container-width`, change `defaultContainerWidth` to match.
 
 ```{note}
-`config.settings.layout` also carries `tabletBreakpoint`, used in the same calculation.
-Keep it in sync with `$tablet-breakpoint` for the same reason.
+`config.settings.layout` also carries `tabletBreakpoint`, 768 by default, which is used in the same calculation.
+It matches VLT's `$largest-mobile-screen` SCSS variable, so if you change VLT's breakpoints, update it as well.
 ```
 
 ### Step 7: Main Index Configuration
@@ -352,7 +369,8 @@ export default applyConfig;
 
 ### Step 8: Import Your Stylesheets
 
-{file}`_main.scss` is the entry point Volto injects after all of VLT's styles. Import your partials there, in the order you want them applied:
+{file}`_main.scss` is the entry point that Volto injects after all of VLT's styles.
+Import your partials there, in the order you want them applied:
 
 ```scss
 // src/theme/_main.scss
@@ -364,15 +382,16 @@ export default applyConfig;
 @import './blocks/teaser';
 ```
 
-{file}`_variables.scss` needs no import. Volto picks it up on its own and injects it ahead of VLT's variables.
+{file}`_variables.scss` needs no import, because Volto injects it on its own.
 
 ## Checkpoint
 
 Restart the frontend and confirm the following before moving on:
 
-- The site renders in your custom font, and the header and footer show their gradients.
-- Links use `--link-foreground-color` rather than the surrounding text color.
-- Opening a page in edit mode and selecting a block shows **Default** and **Charging Bay** in the block's color theme selector.
+- The site renders in Chakra Petch, and the header and footer show their gradients.
+- Links in body text are teal, rather than the color of the surrounding text.
+- Opening a page in edit mode and selecting a Text block shows **Default** and **Charging Bay** in the **Background color** control, and the Charging Bay swatch shows a gradient.
+- Choosing **Charging Bay** for a block gives it the teal wash.
 
 ## Further Reading
 
diff --git a/docs/customizing-volto-light-theme/index.md b/docs/customizing-volto-light-theme/index.md
index 5e97d67cd..e72d036af 100644
--- a/docs/customizing-volto-light-theme/index.md
+++ b/docs/customizing-volto-light-theme/index.md
@@ -14,15 +14,20 @@ myst:
 Level
 :   Intermediate
 
-Customizing Volto Light Theme aims to provide developers with comprehensive knowledge and practical skills for theming in Plone 6's Volto frontend by using and extending Volto Light Theme.
+This training teaches you how to theme the Volto frontend of Plone 6 with Volto Light Theme (VLT).
+You will learn how VLT's design tokens, block themes, and widgets fit together, and how to extend them with your own blocks, listing variations, slots, and components.
 
-The goal of this training is to guide developers in understanding and effectively working with Volto Light Theme to create visually compelling and consistent user interfaces. Due to the scope of the content, the training follows a structured "show and tell" approach, presenting concepts and explaining their usage, while also encouraging participants to put their learning into practice.
+The training follows a "show and tell" approach.
+Each chapter explains a concept, then applies it to a site you build along the way for **the Robotarium**, a workshop that lends robots the way a library lends books.
 
-Participants will explore essential aspects of Volto Light Theme such as setting up theme providers, customizing styles, and understanding how Volto's theming system functions. The training also covers advanced tips, best practices, and lesser-known features to extend Volto Light Theme and create more tailored solutions.
+This training is best suited for developers who have prior experience with Volto and want to deepen their theming knowledge.
 
-The chapters build one site together: **the Robotarium**, a workshop that lends robots the way a library lends books. Each feature is introduced where that site needs it, so the theming concepts arrive attached to a concrete problem rather than in the abstract.
+It was written for the following versions:
 
-This training is best suited for developers who have prior experience with Volto and want to deepen their theming knowledge.
+- Volto Light Theme 8.0.0, both the frontend package `@kitconcept/volto-light-theme` and the backend package `kitconcept.voltolighttheme`
+- Volto 19.4
+- Plone 6.2
+- Cookieplone 2.0
 
 ```{toctree}
 :caption: Volto Light Theme
diff --git a/docs/customizing-volto-light-theme/question-answer.md b/docs/customizing-volto-light-theme/question-answer.md
index 06aa38f6a..4297e39c2 100644
--- a/docs/customizing-volto-light-theme/question-answer.md
+++ b/docs/customizing-volto-light-theme/question-answer.md
@@ -9,7 +9,8 @@ myst:
 
 # Questions and Answers
 
-This chapter collects the questions that come up most often while working through the training, together with the answers you would otherwise have to dig out of the source.
+This chapter collects the questions that come up most often while working through the training.
+Each answer is short, and links to the section that explains it in full.
 
 ## Setup
 
@@ -17,19 +18,17 @@ This chapter collects the questions that come up most often while working throug
 
 Check three things, in order:
 
-1. VLT is declared as the `theme`, not only as an add-on. It is both, and the `addons` entry alone does not apply the theme.
-2. Your project add-on is applied after VLT. VLT must be the last entry in your add-on's `addons` list.
-3. Your stylesheet is reachable from {file}`src/theme/_main.scss`. Volto only picks up that exact filename.
+1. VLT is declared as the `theme` in your add-on's {file}`package.json`, not only listed in `addons`. It needs both entries.
+2. Your stylesheet is {file}`src/theme/_main.scss`, or is imported from it. Volto only picks up that exact filename.
+3. You restarted the frontend after adding the file. Hot reload does not pick up new files.
 
-Restart the frontend after any of these. Adding files is not picked up by hot reload.
-
-### Why is `theme/_main.scss` special?
-
-Volto scans every add-on for {file}`theme/_variables.scss` and {file}`theme/_main.scss` and injects whichever it finds into two fixed points in the theme's stylesheet—variables before VLT's own, main after all of VLT's styles. The filenames are the contract; renaming them silently disables the hook.
+See {ref}`light-theme-insertion-points-label`.
 
 ### Where do I override `$spacing-large` or a breakpoint?
 
-In {file}`src/theme/_variables.scss`. VLT declares its SCSS variables with `!default`, and that file is injected first, so your value wins. Assigning them from {file}`_main.scss` has no effect, because VLT's stylesheets have already been compiled by then.
+In {file}`src/theme/_variables.scss`.
+Assigning SCSS variables in {file}`_main.scss` has no effect, because VLT has already used their values by then.
+See {ref}`light-theme-custom-properties-label`.
 
 ## Styling
 
@@ -39,45 +38,55 @@ In {file}`src/theme/_variables.scss`. VLT declares its SCSS variables with `!def
 
 ### My links are the same color as the surrounding text
 
-That is the default. Links inherit `--theme-foreground-color` so they stay legible against any block theme. Define `--link-foreground-color` in your project to give them a color of their own.
+That is the default: links use the foreground color of the block theme they sit in.
+Set `--link-foreground-color` in your project to give them a color of their own.
+
+### An editor changed a color in the Theming tab, but the site ignores it
+
+Your stylesheet probably sets the same property.
+See {ref}`light-theme-behavior-colors-label` for how to decide who owns each color.
+
+### My gradient palette shows an empty swatch, or unreadable buttons
+
+Some VLT styles read `--theme-color` with `background-color` or `color`, which ignore a gradient.
+See {ref}`the warning about gradient palettes <light-theme-gradient-themes-label>`.
 
 ### Where do the `next--is--...` classes in VLT's CSS come from?
 
-From `config.settings.styleClassNameExtenders`. They describe each block's relationship to its neighbors—same type, same background, first or last of a run—so that vertical spacing can be expressed in CSS instead of in the components. The full list is in the first chapter.
+From functions that VLT adds to `config.settings.styleClassNameExtenders`.
+They describe each block's relationship to its neighbors, so that vertical spacing can be expressed in CSS instead of in the components.
+See {ref}`light-theme-generated-classes-label` for the full list.
 
-## Blocks and widgets
+## Blocks and Widgets
 
 ### My alignment or width buttons appear but do nothing
 
-The field name is almost certainly missing its `:noprefix` suffix. `align` and `align:noprefix` are two different fields, and only the second matches the style definition that injects `--block-alignment`. The same applies to `blockWidth:noprefix` and `size:noprefix`.
+Check two things in the field definition:
 
-### What does `:noprefix` actually do?
+- The field name must end in `:noprefix`, as in `align:noprefix` and `blockWidth:noprefix`. Only those names match the style definitions that inject `--block-alignment` and `--block-width`.
+- The `actions` must be the token names from `config.blocks`. Otherwise the widget stores a style object instead of a token.
 
-It stops the StyleWrapper prefixing the generated CSS class with the field name. A field `align` with value `center` produces `has--align--center`; `align:noprefix` produces `center`. VLT registers its style definitions under the suffixed names, so the suffix is also what makes the lookup match.
+See {ref}`light-theme-style-fields-label` and {ref}`Step 6 of the Cover block <light-theme-cover-actions-label>`.
 
 ### Can I reuse a Volto block id for my own block?
 
-Avoid it. VLT restricts some core blocks—the legacy `hero` among them—and registering under the same key overwrites a core block rather than adding yours, which makes the result depend on add-on ordering. Give project blocks their own key.
+Avoid it.
+Registering under an existing key replaces that block's configuration instead of adding a new block, and the result then depends on the order in which the add-ons are applied.
+Give project blocks their own key.
 
 ### How do I add the background color control to a third-party block?
 
-Register VLT's `defaultStylingSchema` as the block's `schemaEnhancer`, composing it with any enhancer the block already has:
-
-```typescript
-config.blocks.blocksConfig.<blockId> = {
-  ...config.blocks.blocksConfig.<blockId>,
-  schemaEnhancer: composeSchema(
-    config.blocks.blocksConfig.<blockId>.schemaEnhancer,
-    defaultStylingSchema,
-  ),
-};
-```
+Compose VLT's `defaultStylingSchema` with the block's existing `schemaEnhancer`.
+See {ref}`the tip at the end of Step 7 of the Cover block <light-theme-third-party-styling-label>`.
 
 ## Components
 
 ### Should I shadow VLT's header, or swap it?
 
-Swap it. VLT 8 resolves its structural components through the registry, so registering your own and naming it in `config.settings.vlt.components` replaces it without shadowing. Shadowing still works, but it binds you to an internal module path and hides which component is actually active.
+Swap it.
+VLT 8 resolves its structural components through the registry, so registering your own and naming it in `config.settings.vlt.components` replaces it without shadowing.
+Shadowing still works, but it binds you to an internal module path and hides which component is actually active.
+See {ref}`light-theme-swap-components-label`.
 
 ### Slot or component swap?
 
@@ -87,8 +96,10 @@ Use a slot to add something to the layout. Swap a structural component to replac
 
 ### Should I enable it?
 
-Only once every block in your registry is v3-compatible. Block repositories advertise this with a "BMv3 ready" banner. A block left on the older model still renders, but it will not share the container structure of the surrounding page, and the difference shows.
+Only once every block that your site uses supports it.
+See {ref}`light-theme-block-model-v3-label`.
 
 ### Do I need to set categories on VLT's blocks?
 
-No. VLT already assigns them to the blocks it has migrated. Set `category` on your own blocks, and remember that a category only means something if your stylesheets act on the `category-*` class it produces.
+No. VLT already assigns them to the blocks it has migrated.
+For your own blocks, reuse a category only when its rules fit the block, or add a category of your own, as explained in {ref}`light-theme-block-categories-label`.
diff --git a/styles/config/vocabularies/Plone/accept.txt b/styles/config/vocabularies/Plone/accept.txt
index c3984f3f6..3b8bae882 100644
--- a/styles/config/vocabularies/Plone/accept.txt
+++ b/styles/config/vocabularies/Plone/accept.txt
@@ -17,6 +17,7 @@ Brehault
 buildout
 bundler
 Casali
+Chakra
 CMFCore
 configlet
 Cookiecutter
@@ -117,6 +118,7 @@ pdb
 pdbpp
 PDF
 Pellegrini
+Petch
 PhantomJS
 Philipp
 piwik
@@ -165,6 +167,7 @@ REST
 reusability
 reutilization
 RichText
+Robotarium
 Rohberg
 Rossum
 Runyan
@@ -181,6 +184,8 @@ Steffen
 subclassing
 subcomponent
 subfolders
+subsite
+subsites
 subtemplates
 sudo
 superset