From 990fc022879260625d077e412b9fed5cfe9c3460 Mon Sep 17 00:00:00 2001
From: Gab <gabriel.mendonca@azion.com>
Date: Thu, 24 Sep 2026 22:04:46 -0300
Subject: [PATCH 1/3] feat(webkit): move section-title into the marketing
 category

---
 .specs/section-title.md                       | 18 ++++----
 .../section-title/SectionTitle.stories.js     |  3 +-
 packages/webkit/.size-limit.json              |  4 +-
 packages/webkit/catalog.json                  | 16 ++++++--
 packages/webkit/package.json                  |  2 +-
 .../section-title/section-title.test.ts       | 41 ++++++++++++++++++-
 .../section-title/section-title.vue           | 27 ++++++++----
 7 files changed, 84 insertions(+), 27 deletions(-)
 rename apps/storybook/src/stories/components/{content => marketing}/section-title/SectionTitle.stories.js (99%)
 rename packages/webkit/src/components/{content => marketing}/section-title/section-title.test.ts (80%)
 rename packages/webkit/src/components/{content => marketing}/section-title/section-title.vue (83%)

diff --git a/.specs/section-title.md b/.specs/section-title.md
index 3d6189a2f..09c5547c0 100644
--- a/.specs/section-title.md
+++ b/.specs/section-title.md
@@ -1,15 +1,15 @@
 ---
 name: section-title
-category: content
+category: marketing
 structure: monolithic
 status: approved
-spec_version: 2
-checksum: 3a4b15c27d3dda6af9bda55a10bb9e9db13df6865900f9ef805ae97589696e55
+spec_version: 3
+checksum: 5090beab7c8add1bbd4b5109b284e28671723fb8b34b80fa25a2c2d29c4452ee
 figma:
   url: https://www.figma.com/design/QEbHSTFDWfh4VHkBp6NWN3/Azion.com?node-id=7495-24338
   node_id: 7495:24338
 created: 2026-08-11
-last_updated: 2026-08-11
+last_updated: 2026-09-23
 ---
 
 # Section Title — Component Spec
@@ -26,19 +26,21 @@ The framed header row that opens a page section: an optional overline, the secti
 
 ## When NOT to use
 
-- For the page's leading band and its `h1` → use `hero-title` instead.
+- For the page's leading band and its `h1` → use `hero` instead.
 - For the top bar of an application shell → use `global-header` instead.
 - For a plain framed container with arbitrary content → use `frame-box` instead.
 
 ## Related
 
-- `hero-title` — the hero counterpart; renders the page's `h1` at hero scale.
+- `hero` — the opening band; its `Hero.Title` renders the page's `h1` at hero scale.
 - `frame-box` — the frame this component composes.
 - `section-gap` — the empty frame that sets the air before and after a section header; this component holds no vertical air of its own beyond its padding.
 - `overline` — the eyebrow treatment rendered above the headline.
 
 ## Best practices
 
+- Leave `framed` on when the header is a brick of its own in a page column; turn it off when a band composes the header inside a frame it already draws, so the rule and the padding are not drawn twice.
+
 - Keep one `section-title` per section, and let it own the section's `h2` so the page keeps one document outline.
 - Write the eyebrow as one or two words: it is set uppercase and prefixed with `//`, so a sentence in it reads as noise.
 - Reach for `horizontal` when the description is long enough to earn its own column — on a narrow viewport it stacks back under the headline.
@@ -74,6 +76,7 @@ import Button from '@aziontech/webkit/button'
 | `description` | `string` | `''` | false | Supporting sentence under the headline; overridden by the default slot. |
 | `eyebrow` | `string` | `''` | false | Short uppercase overline rendered above the headline. |
 | `kind` | `'centered' \| 'left' \| 'horizontal'` | `'centered'` | false | Layout of the header: `centered` stacks and centers the copy, `left` stacks it at the start edge, `horizontal` sets the headline and its description in two columns. |
+| `framed` | `boolean` | `true` | false | Draw the header's own frame and padding. Turn it off when the header is composed inside a band that already owns both. |
 
 ## Events
 
@@ -90,6 +93,7 @@ import Button from '@aziontech/webkit/button'
 
 - Visual states: `default`
 - `data-kind` mirrors the `kind` prop: `centered` | `left` | `horizontal`
+- `data-framed` present when the header draws its own frame and padding
 
 ## Motion & Animations
 
@@ -120,7 +124,7 @@ _none_
 
 - Visible focus: not applicable to the header itself; controls composed into the `actions` slot keep their own `focus-visible:ring-2 focus-visible:ring-(--ring-color) focus-visible:ring-offset-2 focus-visible:ring-offset-(--bg-canvas)` ring.
 - Keyboard map: none of its own — `Tab` reaches only the controls placed in the `actions` slot, in DOM order.
-- ARIA: the headline is a real `h2` (the page's `h1` belongs to `hero-title`), so no `role` or `aria-label` is added; the frame's rules and corner marks stay `aria-hidden="true"`. In `horizontal` the headline precedes its description in DOM order, so the reading order matches the visual one.
+- ARIA: the headline is a real `h2` (the page's `h1` belongs to `Hero.Title`), so no `role` or `aria-label` is added; the frame's rules and corner marks stay `aria-hidden="true"`. In `horizontal` the headline precedes its description in DOM order, so the reading order matches the visual one.
 - Contrast ≥4.5:1 (text) / ≥3:1 (large + icons): headline on `var(--text-default)`, description on `var(--text-muted)`, both over the page canvas.
 - `motion-reduce:transition-none motion-reduce:transform-none` — not applicable, the component is static.
 - Touch target ≥40×40 px — the `actions` row stretches its children to full width below `sm`, so slotted buttons keep their own target size.
diff --git a/apps/storybook/src/stories/components/content/section-title/SectionTitle.stories.js b/apps/storybook/src/stories/components/marketing/section-title/SectionTitle.stories.js
similarity index 99%
rename from apps/storybook/src/stories/components/content/section-title/SectionTitle.stories.js
rename to apps/storybook/src/stories/components/marketing/section-title/SectionTitle.stories.js
index 6c72b8230..22f25e79e 100644
--- a/apps/storybook/src/stories/components/content/section-title/SectionTitle.stories.js
+++ b/apps/storybook/src/stories/components/marketing/section-title/SectionTitle.stories.js
@@ -8,7 +8,7 @@ const IMPORT_WITH_BUTTON = [IMPORT, "import Button from '@aziontech/webkit/butto
 
 /** @type {import('@storybook/vue3').Meta<typeof SectionTitle>} */
 const meta = {
-  title: 'Components/Content/SectionTitle',
+  title: 'Components/Marketing/SectionTitle',
   component: SectionTitle,
   tags: ['autodocs'],
   parameters: {
@@ -172,4 +172,3 @@ export const WithActions = {
     }
   }
 }
-
diff --git a/packages/webkit/.size-limit.json b/packages/webkit/.size-limit.json
index dbcbf8e11..05f4dde7e 100644
--- a/packages/webkit/.size-limit.json
+++ b/packages/webkit/.size-limit.json
@@ -36,8 +36,8 @@
   },
   {
     "name": "section-title",
-    "path": "src/components/content/section-title/section-title.vue",
-    "limit": "4 KB"
+    "path": "src/components/marketing/section-title/section-title.vue",
+    "limit": "3 KB"
   },
   {
     "name": "hero-title",
diff --git a/packages/webkit/catalog.json b/packages/webkit/catalog.json
index 039f4a19f..735b9f3ff 100644
--- a/packages/webkit/catalog.json
+++ b/packages/webkit/catalog.json
@@ -2974,10 +2974,10 @@
     },
     "section-title": {
       "import": "@aziontech/webkit/section-title",
-      "target": "./src/components/content/section-title/section-title.vue",
+      "target": "./src/components/marketing/section-title/section-title.vue",
       "kind": "component",
       "treeShakeableImport": "@aziontech/webkit/section-title",
-      "category": "content",
+      "category": "marketing",
       "structure": "monolithic",
       "status": "approved",
       "props": [
@@ -3008,6 +3008,13 @@
           "default": "'centered'",
           "required": "false",
           "doc": "Layout of the header: `centered` stacks and centers the copy, `left` stacks it at the start edge, `horizontal` sets the headline and its description in two columns."
+        },
+        {
+          "name": "framed",
+          "type": "boolean",
+          "default": "true",
+          "required": "false",
+          "doc": "Draw the header's own frame and padding. Turn it off when the header is composed inside a band that already owns both."
         }
       ],
       "slots": [
@@ -3029,17 +3036,18 @@
         "For a wide band whose headline and supporting sentence should sit side by side rather than stacked — `kind=\"horizontal\"`."
       ],
       "avoidWhen": [
-        "For the page's leading band and its `h1` → use `hero-title` instead.",
+        "For the page's leading band and its `h1` → use `hero` instead.",
         "For the top bar of an application shell → use `global-header` instead.",
         "For a plain framed container with arbitrary content → use `frame-box` instead."
       ],
       "related": [
-        "hero-title` — the hero counterpart; renders the page's `h1` at hero scale.",
+        "hero` — the opening band; its `Hero.Title` renders the page's `h1` at hero scale.",
         "frame-box` — the frame this component composes.",
         "section-gap` — the empty frame that sets the air before and after a section header; this component holds no vertical air of its own beyond its padding.",
         "overline` — the eyebrow treatment rendered above the headline."
       ],
       "bestPractices": [
+        "Leave `framed` on when the header is a brick of its own in a page column; turn it off when a band composes the header inside a frame it already draws, so the rule and the padding are not drawn twice.",
         "Keep one `section-title` per section, and let it own the section's `h2` so the page keeps one document outline.",
         "Write the eyebrow as one or two words: it is set uppercase and prefixed with `//`, so a sentence in it reads as noise.",
         "Reach for `horizontal` when the description is long enough to earn its own column — on a narrow viewport it stacks back under the headline.",
diff --git a/packages/webkit/package.json b/packages/webkit/package.json
index d69e67e99..8eb2fc065 100644
--- a/packages/webkit/package.json
+++ b/packages/webkit/package.json
@@ -132,7 +132,7 @@
     "./card-box": "./src/components/content/card-box/card-box.vue",
     "./card-pricing": "./src/components/content/card-pricing/card-pricing.vue",
     "./hero-title": "./src/components/content/hero-title/hero-title.vue",
-    "./section-title": "./src/components/content/section-title/section-title.vue",
+    "./section-title": "./src/components/marketing/section-title/section-title.vue",
     "./item": "./src/components/content/item/index.ts",
     "./item-root": "./src/components/content/item/item.vue",
     "./item-group": "./src/components/content/item/item-group.vue",
diff --git a/packages/webkit/src/components/content/section-title/section-title.test.ts b/packages/webkit/src/components/marketing/section-title/section-title.test.ts
similarity index 80%
rename from packages/webkit/src/components/content/section-title/section-title.test.ts
rename to packages/webkit/src/components/marketing/section-title/section-title.test.ts
index 177937a09..3efaa417c 100644
--- a/packages/webkit/src/components/content/section-title/section-title.test.ts
+++ b/packages/webkit/src/components/marketing/section-title/section-title.test.ts
@@ -2,13 +2,13 @@ import { composeStories } from '@storybook/vue3'
 import { render } from '@testing-library/vue'
 import { describe, expect, it } from 'vitest'
 
-import * as stories from '../../../../../../apps/storybook/src/stories/components/content/section-title/SectionTitle.stories'
+import * as stories from '../../../../../../apps/storybook/src/stories/components/marketing/section-title/SectionTitle.stories'
 import { expectNoA11yViolations } from '../../../test/axe'
 import SectionTitle from './section-title.vue'
 
 const { Default, Kinds, WithActions } = composeStories(stories)
 
-const TESTID = 'content-section-title'
+const TESTID = 'marketing-section-title'
 
 const props = { title: 'Everything runs at the edge' }
 
@@ -157,4 +157,41 @@ describe('SectionTitle', () => {
       ])
     })
   })
+
+  describe('framed', () => {
+    it('draws its own frame by default', () => {
+      const { getByTestId } = render(SectionTitle, { props: { title: 'Platform' } })
+      const root = getByTestId(TESTID)
+
+      expect(root).toHaveAttribute('data-framed')
+      // the frame resolves to FrameBox, which carries the resolved side list
+      expect(root).toHaveAttribute('data-borders')
+    })
+
+    it('renders as a plain block when framed is false', () => {
+      const { getByTestId } = render(SectionTitle, {
+        props: { title: 'Platform', framed: false }
+      })
+      const root = getByTestId(TESTID)
+
+      expect(root).not.toHaveAttribute('data-framed')
+      expect(root).not.toHaveAttribute('data-borders')
+      expect(root).not.toHaveAttribute('data-marks')
+    })
+
+    it('keeps its copy and its heading level unframed', () => {
+      const { getByRole, getByText } = render(SectionTitle, {
+        props: {
+          title: 'Platform',
+          eyebrow: 'Build',
+          description: 'One sentence.',
+          framed: false
+        }
+      })
+
+      expect(getByRole('heading', { level: 2, name: 'Platform' })).toBeInTheDocument()
+      expect(getByText('Build')).toBeInTheDocument()
+      expect(getByText('One sentence.')).toBeInTheDocument()
+    })
+  })
 })
diff --git a/packages/webkit/src/components/content/section-title/section-title.vue b/packages/webkit/src/components/marketing/section-title/section-title.vue
similarity index 83%
rename from packages/webkit/src/components/content/section-title/section-title.vue
rename to packages/webkit/src/components/marketing/section-title/section-title.vue
index 97030a05f..54e63777e 100644
--- a/packages/webkit/src/components/content/section-title/section-title.vue
+++ b/packages/webkit/src/components/marketing/section-title/section-title.vue
@@ -21,12 +21,15 @@
     eyebrow?: string
     /** Layout of the header: `centered` stacks and centers the copy, `left` stacks it at the start edge, `horizontal` sets the headline and its description in two columns. */
     kind?: SectionTitleKind
+    /** Draw the header's own frame and padding. Turn it off when the header is composed inside a band that already owns both. */
+    framed?: boolean
   }
 
   const props = withDefaults(defineProps<Props>(), {
     description: '',
     eyebrow: '',
-    kind: 'centered'
+    kind: 'centered',
+    framed: true
   })
 
   const slots = defineSlots<{
@@ -37,12 +40,19 @@
   const attrs = useAttrs()
 
   const testId = computed(
-    () => (attrs['data-testid'] as string | undefined) ?? 'content-section-title'
+    () => (attrs['data-testid'] as string | undefined) ?? 'marketing-section-title'
   )
 
   const hasDescription = computed<boolean>(
     () => Boolean(slots.default) || props.description.length > 0
   )
+
+  // Unframed, the header is a plain block: the band composing it owns the rule and the
+  // padding, so drawing either here would draw it twice.
+  const frame = computed(() => (props.framed ? FrameBox : 'div'))
+  const frameProps = computed(() =>
+    props.framed ? { flush: true, borders: 'y', marks: 'bottom' } : {}
+  )
 </script>
 
 <template>
@@ -50,17 +60,16 @@
        rule is what divides the title from the section body, so the row adds no outer margin
        and no second line. The header holds no vertical air of its own beyond this padding —
        the rhythm around it belongs to the SectionGap frames on either side. -->
-  <FrameBox
-    v-bind="$attrs"
-    flush
-    borders="y"
-    marks="bottom"
+  <component
+    :is="frame"
+    v-bind="{ ...$attrs, ...frameProps }"
     :data-testid="testId"
     :data-kind="kind"
+    :data-framed="props.framed || null"
     class="group"
   >
     <div
-      class="flex flex-col items-start gap-(--spacing-xl) px-(--spacing-xl) py-(--spacing-xxl) group-data-[kind=centered]:items-center"
+      class="flex flex-col items-start gap-(--spacing-xl) group-data-[framed]:px-(--spacing-xl) group-data-[framed]:py-(--spacing-xxl) group-data-[kind=centered]:items-center"
     >
       <!-- Horizontal: the overline leads, then the headline and its description share a
            three-column grid — headline in the first column, description in the third, the
@@ -127,5 +136,5 @@
         <slot name="actions" />
       </div>
     </div>
-  </FrameBox>
+  </component>
 </template>

From c6d633ed507fa2d542702d9c27a1464d4b9d7190 Mon Sep 17 00:00:00 2001
From: Gab <gabriel.mendonca@azion.com>
Date: Mon, 28 Sep 2026 07:23:44 -0300
Subject: [PATCH 2/3] feat(webkit): add a size scale to section-title

---
 .specs/section-title.md                       | 16 ++++--
 .../section-title/SectionTitle.stories.js     | 54 ++++++++++++++++++-
 packages/webkit/.size-limit.json              |  2 +-
 packages/webkit/catalog.json                  | 10 +++-
 .../section-title/section-title.test.ts       | 33 +++++++++++-
 .../marketing/section-title/section-title.vue | 16 ++++--
 6 files changed, 119 insertions(+), 12 deletions(-)

diff --git a/.specs/section-title.md b/.specs/section-title.md
index 09c5547c0..751f25a25 100644
--- a/.specs/section-title.md
+++ b/.specs/section-title.md
@@ -4,12 +4,12 @@ category: marketing
 structure: monolithic
 status: approved
 spec_version: 3
-checksum: 5090beab7c8add1bbd4b5109b284e28671723fb8b34b80fa25a2c2d29c4452ee
+checksum: 3d3a1e4ec59dd948f5f2f4d236ce30ec39428bc5dd991f0903478658c5e3c7f9
 figma:
   url: https://www.figma.com/design/QEbHSTFDWfh4VHkBp6NWN3/Azion.com?node-id=7495-24338
   node_id: 7495:24338
 created: 2026-08-11
-last_updated: 2026-09-23
+last_updated: 2026-09-25
 ---
 
 # Section Title — Component Spec
@@ -41,7 +41,8 @@ The framed header row that opens a page section: an optional overline, the secti
 
 - Leave `framed` on when the header is a brick of its own in a page column; turn it off when a band composes the header inside a frame it already draws, so the rule and the padding are not drawn twice.
 
-- Keep one `section-title` per section, and let it own the section's `h2` so the page keeps one document outline.
+- Keep one `section-title` per section, and let it own the section's `h2` so the page keeps one document outline. `size` changes the headline's step on the type scale, never its heading level — a page with a `large` and a `small` header still reads as two `h2`s.
+- Leave `size` at `medium` for an ordinary section opener. Reach for `large` only where the headline is the band's whole statement, and for `small` where the header opens a subsection inside a band that already has one.
 - Write the eyebrow as one or two words: it is set uppercase and prefixed with `//`, so a sentence in it reads as noise.
 - Reach for `horizontal` when the description is long enough to earn its own column — on a narrow viewport it stacks back under the headline.
 - Put the section's CTAs in the `actions` slot rather than in the body; the slot already stacks them fluid below `sm` and aligns them with the chosen `kind` above it.
@@ -76,6 +77,7 @@ import Button from '@aziontech/webkit/button'
 | `description` | `string` | `''` | false | Supporting sentence under the headline; overridden by the default slot. |
 | `eyebrow` | `string` | `''` | false | Short uppercase overline rendered above the headline. |
 | `kind` | `'centered' \| 'left' \| 'horizontal'` | `'centered'` | false | Layout of the header: `centered` stacks and centers the copy, `left` stacks it at the start edge, `horizontal` sets the headline and its description in two columns. |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | false | Step of the headline on the heading scale: `small` for a subsection inside a band, `medium` for an ordinary section opener, `large` for a band whose headline is the statement. |
 | `framed` | `boolean` | `true` | false | Draw the header's own frame and padding. Turn it off when the header is composed inside a band that already owns both. |
 
 ## Events
@@ -93,6 +95,7 @@ import Button from '@aziontech/webkit/button'
 
 - Visual states: `default`
 - `data-kind` mirrors the `kind` prop: `centered` | `left` | `horizontal`
+- `data-size` mirrors the `size` prop: `small` | `medium` | `large`
 - `data-framed` present when the header draws its own frame and padding
 
 ## Motion & Animations
@@ -103,7 +106,9 @@ _none_
 
 | Region | Token (DESIGN.md) |
 |---|---|
-| typography (headline) | `.text-heading-xl` |
+| typography (headline, `size="small"`) | `.text-heading-lg` |
+| typography (headline, `size="medium"`) | `.text-heading-xl` |
+| typography (headline, `size="large"`) | `.text-heading-2xl` |
 | typography (description) | `.text-heading-sm` |
 | headline text | `var(--text-default)` |
 | description text | `var(--text-muted)` |
@@ -132,7 +137,8 @@ _none_
 ## Stories (Storybook)
 
 - Default
-- Kinds — composite story rendering every `kind` value stacked, so the three layouts can be compared (justified: `kind` is the component's only enum axis and the difference is structural)
+- Kinds — composite story rendering every `kind` value stacked, so the three layouts can be compared (justified: the difference between the layouts is structural)
+- Sizes — composite story rendering every `size` value stacked, so the three steps of the headline scale can be compared
 - WithActions — an `actions` row under the description (justified: the slot owns its own responsive layout, which no prop-driven story shows)
 
 ## Constraints — DO NOT
diff --git a/apps/storybook/src/stories/components/marketing/section-title/SectionTitle.stories.js b/apps/storybook/src/stories/components/marketing/section-title/SectionTitle.stories.js
index 22f25e79e..8b67c8882 100644
--- a/apps/storybook/src/stories/components/marketing/section-title/SectionTitle.stories.js
+++ b/apps/storybook/src/stories/components/marketing/section-title/SectionTitle.stories.js
@@ -56,6 +56,17 @@ const meta = {
         defaultValue: { summary: "'centered'" }
       }
     },
+    size: {
+      control: 'inline-radio',
+      options: ['small', 'medium', 'large'],
+      description:
+        'Step of the headline on the heading scale: `small` for a subsection inside a band, `medium` for an ordinary section opener, `large` for a band whose headline is the statement.',
+      table: {
+        category: 'props',
+        type: { summary: "'small' | 'medium' | 'large'" },
+        defaultValue: { summary: "'medium'" }
+      }
+    },
     default: {
       control: false,
       description: 'Description body; replaces the `description` prop when provided.',
@@ -71,7 +82,8 @@ const meta = {
     title: 'Everything runs at the edge',
     description: 'One platform for applications, security and observability.',
     eyebrow: 'Platform',
-    kind: 'centered'
+    kind: 'centered',
+    size: 'medium'
   }
 }
 
@@ -143,6 +155,46 @@ export const Kinds = {
   }
 }
 
+const SIZES_TEMPLATE = `<div>
+  <SectionTitle
+    size="small"
+    kind="left"
+    eyebrow="Small"
+    title="A subsection inside a band"
+    description="The headline drops a step so it opens a part of a section without competing with the section's own header."
+  />
+  <SectionTitle
+    size="medium"
+    kind="left"
+    eyebrow="Medium"
+    title="An ordinary section opener"
+    description="The default step, and the one nearly every section header wants."
+  />
+  <SectionTitle
+    size="large"
+    kind="left"
+    eyebrow="Large"
+    title="The headline is the statement"
+    description="For a band that carries one claim and little else — the copy under it stays at reading size."
+  />
+</div>`
+
+/** @type {import('@storybook/vue3').StoryObj<typeof SectionTitle>} */
+export const Sizes = {
+  render: () => ({ components: { SectionTitle }, template: SIZES_TEMPLATE }),
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      controls: { disable: true },
+      description: {
+        story:
+          'The three steps of the headline scale, stacked. `size` moves the headline between `text-heading-lg`, `text-heading-xl` and `text-heading-2xl` — the description stays at reading size in all three, and the heading stays an `h2`, so the page outline is unaffected by how loud a header is.'
+      },
+      source: { code: toSfc(IMPORT, SIZES_TEMPLATE) }
+    }
+  }
+}
+
 const WITH_ACTIONS_TEMPLATE = `<SectionTitle
   eyebrow="Platform"
   title="Everything runs at the edge"
diff --git a/packages/webkit/.size-limit.json b/packages/webkit/.size-limit.json
index 05f4dde7e..b2418dde9 100644
--- a/packages/webkit/.size-limit.json
+++ b/packages/webkit/.size-limit.json
@@ -37,7 +37,7 @@
   {
     "name": "section-title",
     "path": "src/components/marketing/section-title/section-title.vue",
-    "limit": "3 KB"
+    "limit": "3.5 KB"
   },
   {
     "name": "hero-title",
diff --git a/packages/webkit/catalog.json b/packages/webkit/catalog.json
index 735b9f3ff..70369d8fc 100644
--- a/packages/webkit/catalog.json
+++ b/packages/webkit/catalog.json
@@ -3009,6 +3009,13 @@
           "required": "false",
           "doc": "Layout of the header: `centered` stacks and centers the copy, `left` stacks it at the start edge, `horizontal` sets the headline and its description in two columns."
         },
+        {
+          "name": "size",
+          "type": "'small' | 'medium' | 'large'",
+          "default": "'medium'",
+          "required": "false",
+          "doc": "Step of the headline on the heading scale: `small` for a subsection inside a band, `medium` for an ordinary section opener, `large` for a band whose headline is the statement."
+        },
         {
           "name": "framed",
           "type": "boolean",
@@ -3048,7 +3055,8 @@
       ],
       "bestPractices": [
         "Leave `framed` on when the header is a brick of its own in a page column; turn it off when a band composes the header inside a frame it already draws, so the rule and the padding are not drawn twice.",
-        "Keep one `section-title` per section, and let it own the section's `h2` so the page keeps one document outline.",
+        "Keep one `section-title` per section, and let it own the section's `h2` so the page keeps one document outline. `size` changes the headline's step on the type scale, never its heading level — a page with a `large` and a `small` header still reads as two `h2`s.",
+        "Leave `size` at `medium` for an ordinary section opener. Reach for `large` only where the headline is the band's whole statement, and for `small` where the header opens a subsection inside a band that already has one.",
         "Write the eyebrow as one or two words: it is set uppercase and prefixed with `//`, so a sentence in it reads as noise.",
         "Reach for `horizontal` when the description is long enough to earn its own column — on a narrow viewport it stacks back under the headline.",
         "Put the section's CTAs in the `actions` slot rather than in the body; the slot already stacks them fluid below `sm` and aligns them with the chosen `kind` above it.",
diff --git a/packages/webkit/src/components/marketing/section-title/section-title.test.ts b/packages/webkit/src/components/marketing/section-title/section-title.test.ts
index 3efaa417c..5c9edab1f 100644
--- a/packages/webkit/src/components/marketing/section-title/section-title.test.ts
+++ b/packages/webkit/src/components/marketing/section-title/section-title.test.ts
@@ -6,7 +6,7 @@ import * as stories from '../../../../../../apps/storybook/src/stories/component
 import { expectNoA11yViolations } from '../../../test/axe'
 import SectionTitle from './section-title.vue'
 
-const { Default, Kinds, WithActions } = composeStories(stories)
+const { Default, Kinds, Sizes, WithActions } = composeStories(stories)
 
 const TESTID = 'marketing-section-title'
 
@@ -45,6 +45,27 @@ describe('SectionTitle', () => {
     expect(getByTestId(TESTID)).toHaveAttribute('data-kind', 'centered')
   })
 
+  it.each(['small', 'medium', 'large'] as const)('reflects size="%s" on data-size', (size) => {
+    const { getByTestId } = render(SectionTitle, { props: { ...props, size } })
+
+    expect(getByTestId(TESTID)).toHaveAttribute('data-size', size)
+  })
+
+  it('defaults to the medium size', () => {
+    const { getByTestId } = render(SectionTitle, { props })
+
+    expect(getByTestId(TESTID)).toHaveAttribute('data-size', 'medium')
+  })
+
+  it.each(['small', 'medium', 'large'] as const)(
+    'keeps the headline an h2 at size="%s"',
+    (size) => {
+      const { getByRole } = render(SectionTitle, { props: { ...props, size } })
+
+      expect(getByRole('heading', { level: 2 })).toHaveTextContent('Everything runs at the edge')
+    }
+  )
+
   it.each(['centered', 'left', 'horizontal'] as const)(
     'keeps the headline before its description in DOM order when kind="%s"',
     (kind) => {
@@ -148,6 +169,16 @@ describe('SectionTitle', () => {
       ])
     })
 
+    it('renders the Sizes story with one header per step', () => {
+      const { getAllByTestId } = render(Sizes())
+
+      expect(getAllByTestId(TESTID).map((el) => el.getAttribute('data-size'))).toEqual([
+        'small',
+        'medium',
+        'large'
+      ])
+    })
+
     it('renders the WithActions story with both CTAs', () => {
       const { getAllByRole } = render(WithActions())
 
diff --git a/packages/webkit/src/components/marketing/section-title/section-title.vue b/packages/webkit/src/components/marketing/section-title/section-title.vue
index 54e63777e..dd9c020eb 100644
--- a/packages/webkit/src/components/marketing/section-title/section-title.vue
+++ b/packages/webkit/src/components/marketing/section-title/section-title.vue
@@ -11,6 +11,8 @@
 
   /** Layout of the header row. */
   export type SectionTitleKind = 'centered' | 'left' | 'horizontal'
+  /** Step of the headline on the heading scale. */
+  export type SectionTitleSize = 'small' | 'medium' | 'large'
 
   interface Props {
     /** Headline of the section, rendered as the section's `h2`. */
@@ -21,6 +23,8 @@
     eyebrow?: string
     /** Layout of the header: `centered` stacks and centers the copy, `left` stacks it at the start edge, `horizontal` sets the headline and its description in two columns. */
     kind?: SectionTitleKind
+    /** Step of the headline on the heading scale: `small` for a subsection inside a band, `medium` for an ordinary section opener, `large` for a band whose headline is the statement. */
+    size?: SectionTitleSize
     /** Draw the header's own frame and padding. Turn it off when the header is composed inside a band that already owns both. */
     framed?: boolean
   }
@@ -29,6 +33,7 @@
     description: '',
     eyebrow: '',
     kind: 'centered',
+    size: 'medium',
     framed: true
   })
 
@@ -51,7 +56,7 @@
   // padding, so drawing either here would draw it twice.
   const frame = computed(() => (props.framed ? FrameBox : 'div'))
   const frameProps = computed(() =>
-    props.framed ? { flush: true, borders: 'y', marks: 'bottom' } : {}
+    props.framed ? { flush: true, borders: 'y', marks: 'all' } : {}
   )
 </script>
 
@@ -65,6 +70,7 @@
     v-bind="{ ...$attrs, ...frameProps }"
     :data-testid="testId"
     :data-kind="kind"
+    :data-size="size"
     :data-framed="props.framed || null"
     class="group"
   >
@@ -86,7 +92,9 @@
           >{{ eyebrow }}</Overline
         >
         <div class="grid gap-(--spacing-xl) md:grid-cols-3">
-          <h2 class="m-0 text-balance text-heading-xl text-(--text-default)">
+          <h2
+            class="m-0 text-balance text-(--text-default) group-data-[size=small]:text-heading-lg group-data-[size=medium]:text-heading-xl group-data-[size=large]:text-heading-2xl"
+          >
             {{ title }}
           </h2>
           <p
@@ -113,7 +121,9 @@
           show-cursor
           >{{ eyebrow }}</Overline
         >
-        <h2 class="m-0 text-balance text-heading-xl text-(--text-default)">
+        <h2
+          class="m-0 text-balance text-(--text-default) group-data-[size=small]:text-heading-lg group-data-[size=medium]:text-heading-xl group-data-[size=large]:text-heading-2xl"
+        >
           {{ title }}
         </h2>
         <p

From 9ff13432db9413150620f62552e2d4c4858132c4 Mon Sep 17 00:00:00 2001
From: Gab <gabriel.mendonca@azion.com>
Date: Mon, 28 Sep 2026 07:40:28 -0300
Subject: [PATCH 3/3] style(webkit): drop the implementation comments from
 section-title

---
 .../section-title/section-title.test.ts       |  5 -----
 .../marketing/section-title/section-title.vue | 20 -------------------
 2 files changed, 25 deletions(-)

diff --git a/packages/webkit/src/components/marketing/section-title/section-title.test.ts b/packages/webkit/src/components/marketing/section-title/section-title.test.ts
index 5c9edab1f..0b205eda6 100644
--- a/packages/webkit/src/components/marketing/section-title/section-title.test.ts
+++ b/packages/webkit/src/components/marketing/section-title/section-title.test.ts
@@ -24,8 +24,6 @@ describe('SectionTitle', () => {
     const { getByTestId } = render(SectionTitle, { props })
     const root = getByTestId(TESTID)
 
-    // flush="top" is subtracted from borders="y", so the header keeps only its bottom rule —
-    // the divider between the header and the section body.
     expect(root).toHaveAttribute('data-flush', 'top')
     expect(root).toHaveAttribute('data-borders', 'bottom')
   })
@@ -78,8 +76,6 @@ describe('SectionTitle', () => {
 
       expect(heading).toHaveTextContent('Everything runs at the edge')
       expect(paragraph).toHaveTextContent('One platform.')
-      // Node.DOCUMENT_POSITION_FOLLOWING === 4: the description follows the headline, so the
-      // reading order matches the visual one in every layout — including the two-column one.
       expect(heading.compareDocumentPosition(paragraph) & 4).toBe(4)
     }
   )
@@ -195,7 +191,6 @@ describe('SectionTitle', () => {
       const root = getByTestId(TESTID)
 
       expect(root).toHaveAttribute('data-framed')
-      // the frame resolves to FrameBox, which carries the resolved side list
       expect(root).toHaveAttribute('data-borders')
     })
 
diff --git a/packages/webkit/src/components/marketing/section-title/section-title.vue b/packages/webkit/src/components/marketing/section-title/section-title.vue
index dd9c020eb..0e37dc236 100644
--- a/packages/webkit/src/components/marketing/section-title/section-title.vue
+++ b/packages/webkit/src/components/marketing/section-title/section-title.vue
@@ -52,8 +52,6 @@
     () => Boolean(slots.default) || props.description.length > 0
   )
 
-  // Unframed, the header is a plain block: the band composing it owns the rule and the
-  // padding, so drawing either here would draw it twice.
   const frame = computed(() => (props.framed ? FrameBox : 'div'))
   const frameProps = computed(() =>
     props.framed ? { flush: true, borders: 'y', marks: 'all' } : {}
@@ -61,10 +59,6 @@
 </script>
 
 <template>
-  <!-- There is no gap around the frame: it spans the column edge to edge and its own bottom
-       rule is what divides the title from the section body, so the row adds no outer margin
-       and no second line. The header holds no vertical air of its own beyond this padding —
-       the rhythm around it belongs to the SectionGap frames on either side. -->
   <component
     :is="frame"
     v-bind="{ ...$attrs, ...frameProps }"
@@ -77,10 +71,6 @@
     <div
       class="flex flex-col items-start gap-(--spacing-xl) group-data-[framed]:px-(--spacing-xl) group-data-[framed]:py-(--spacing-xxl) group-data-[kind=centered]:items-center"
     >
-      <!-- Horizontal: the overline leads, then the headline and its description share a
-           three-column grid — headline in the first column, description in the third, the
-           middle column left as air. Below `md` the grid collapses to one column and the
-           description falls back under the headline, in reading order. -->
       <div
         v-if="kind === 'horizontal'"
         class="flex w-full flex-col gap-(--spacing-lg)"
@@ -106,15 +96,10 @@
         </div>
       </div>
 
-      <!-- Centered and left share one stacked column; only the alignment differs, which is
-           why it switches on the root's `data-kind` instead of on a second template. -->
       <div
         v-else
         class="flex w-full max-w-(--container-2xl) flex-col gap-(--spacing-lg) group-data-[kind=centered]:items-center group-data-[kind=centered]:text-center"
       >
-        <!-- The overline anatomy the framed sections share: a `//` prefix, the label in the
-             accent, and the blinking cursor. All three are props of Overline, so this is the
-             DS component configured — not a copy of its look. -->
         <Overline
           v-if="eyebrow"
           prefix="//"
@@ -134,11 +119,6 @@
         </p>
       </div>
 
-      <!-- The actions row stacks and goes fluid below `sm` — a section CTA is a primary
-           target and a thumb should not have to aim at a shrink-wrapped label — and
-           `[&>*]:w-full` is what reaches the slotted controls, since the wrapper's own width
-           says nothing about theirs. From `sm` up it is a content-width row, centered only
-           when the header is. -->
       <div
         v-if="slots.actions"
         class="flex w-full flex-col items-stretch gap-(--spacing-md) [&>*]:w-full sm:w-auto sm:flex-row sm:items-center sm:[&>*]:w-auto sm:group-data-[kind=centered]:justify-center"