From 0596542012224906aed3ca238c3a9a7d4f8f8f8e Mon Sep 17 00:00:00 2001
From: Bartek Szopka <bartek.szopka@canonical.com>
Date: Fri, 16 Feb 2024 16:53:26 +0100
Subject: [PATCH] Docs improvements based on comments

---
 templates/docs/patterns/strip/index.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/templates/docs/patterns/strip/index.md b/templates/docs/patterns/strip/index.md
index ad07030ab2..9852226804 100644
--- a/templates/docs/patterns/strip/index.md
+++ b/templates/docs/patterns/strip/index.md
@@ -6,12 +6,18 @@ context:
 
 The strip pattern provides a full width strip container in which to wrap a grid. It is an alternative to the section component, that surrounds its content with a padding both on the top and bottom, and is used usually when a change of the background is needed or to separate different sections of the page.
 
+Strips, similarly to sections, come in 3 sizes: regular (`.p-strip`), [deep](#deep-strip) (`.p-strip is-deep`) and [shallow](#shallow-strip) (`.p-strip is-shallow`).
+
+They fully support [theming](#themes). Changing the theme on the strip component itself will apply the background colour to the entire strip, and affect the theme of the strip content. You can choose between regular strip (with default background of the theme), or highlighted strip (with am alternative lighter version of the background colour).
+
 A `.p-strip` container should always be the parent of a `.row` (from the [Grid pattern](/docs/patterns/grid/)) and never the other way around.
 
 ## Regular strip
 
 The strip component is rarely used on its own as a container with just `.p-strip` class name. It is usually combined with other variants described below to provide a specific visual style.
 
+If you believe you need a plain `.p-strip` container, you likely want to use a [section](/docs/patterns/section) instead.
+
 ## Themes
 
 The strip component can be used to change the background colour of the section, by applying one of the theme class names, such as `is-dark`, `is-light` or `is-paper`.
@@ -23,7 +29,7 @@ View example of the strip dark pattern
 <div class="p-notification--caution">
   <div class="p-notification__content">
     <h3 class="p-notification__title">Deprecated</h3>
-    <p class="p-notification__message">In Vanilla 4.8.0 with the introduction of new theming system the old <code>p-strip--dark</code> is deprecated. Use a strip is <code>is-dark</code> class instead.</p>
+    <p class="p-notification__message">In Vanilla 4.8.0 with the introduction of new theming system the old <code>p-strip--dark</code> is deprecated. Use a strip with <code>is-dark</code> class instead.</p>
   </div>
 </div>