docs: add heading component in a dedicated components page

src/data/nav-items.yaml

@@ -112,6 +112,8 @@
       path: /components/file-uploader/usage/
     - title: Form
       path: /components/form/usage/
+    - title: Heading
+      path: /components/heading/usage/
     - title: Inline loading
       path: /components/inline-loading/usage/
     - title: Link

src/pages/components/heading/accessibility.mdx

@@ -0,0 +1,80 @@
+---
+title: Heading
+description:
+  The Heading component automatically infers the appropriate heading level based
+  on the Section component, helping maintain proper document structure without
+  manual specification.
+tabs: ['Usage', 'Style', 'Code', 'Accessibility']
+---
+
+<PageDescription>
+
+The Heading component maintains semantic HTML structure by automatically
+inferring heading levels, ensuring accessibility is preserved while simplifying
+development.
+
+</PageDescription>
+
+<AnchorLinks>
+  <AnchorLink>What Carbon provides</AnchorLink>
+  <AnchorLink>Design recommendations</AnchorLink>
+  <AnchorLink>Development considerations</AnchorLink>
+</AnchorLinks>
+
+## What Carbon provides
+
+The Heading component automatically manages semantic heading levels (h1-h6)
+through Section nesting, ensuring proper document structure for assistive
+technologies without manual intervention.
+
+For information on typography and visual styling, see
+[Typography overview](/elements/typography/overview).
+
+### Keyboard support
+
+The Heading component itself has no interactive keyboard behavior. Screen reader
+users navigate headings using:
+
+| Key         | Action                           |
+| ----------- | -------------------------------- |
+| `H`         | Jump to next heading (JAWS/NVDA) |
+| `Shift + H` | Jump to previous heading         |
+| `1-6`       | Jump to specific heading level   |
+
+### Screen reader announcements
+
+Screen readers announce:
+
+- The heading level (e.g., "Heading level 2")
+- The heading text content
+- The semantic structure, not visual styling
+
+## Development considerations
+
+### Implementation requirements
+
+```jsx
+// Required: Always wrap Heading in Section
+<Section>
+  <Heading>Accessible heading</Heading>
+</Section>
+
+// Semantic HTML elements
+<Section as="article">
+  <Heading>Article title</Heading>
+</Section>
+
+<Section as="nav">
+  <Heading>Navigation menu</Heading>
+</Section>
+```
+
+### WCAG 2.1 compliance
+
+The Heading component supports:
+
+| Success Criterion            | Level | Requirement                          |
+| ---------------------------- | ----- | ------------------------------------ |
+| 1.3.1 Info and Relationships | A     | Semantic heading structure preserved |
+| 2.4.6 Headings and Labels    | AA    | Headings describe topics/purposes    |
+| 2.4.10 Section Headings      | AAA   | Content organized with headings      |

src/pages/components/heading/code.mdx

@@ -0,0 +1,134 @@
+---
+title: Heading
+description:
+  The Heading component automatically infers the appropriate heading level based
+  on the Section component, helping maintain proper document structure without
+  manual specification.
+tabs: ['Usage', 'Style', 'Code', 'Accessibility']
+---
+
+<PageDescription>
+
+Preview the Heading component with the React live demo. For detailed code usage
+documentation, see the Storybooks for each framework below.
+
+</PageDescription>
+
+## Documentation
+
+<Row className="resource-card-group">
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+    subTitle="React"
+    href="https://react.carbondesignsystem.com/?path=/story/components-heading--default"
+    >
+
+<MdxIcon name="react" />
+
+  </ResourceCard>
+</Column>
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+    subTitle="Web Components"
+    href="https://web-components.carbondesignsystem.com/?path=/docs/components-heading--overview"
+    >
+
+<MdxIcon name="webcomponents" />
+
+  </ResourceCard>
+</Column>
+</Row>
+
+## Live demo
+
+<StorybookDemo
+  themeSelector
+  url="https://react.carbondesignsystem.com"
+  variants={[
+    {
+      label: 'Default',
+      variant: 'components-heading--default',
+    },
+    {
+      label: 'Custom level',
+      variant: 'components-heading--custom-level',
+    },
+  ]}
+/>
+
+## Code examples
+
+### Installation
+
+```bash
+npm install @carbon/react
+```
+
+### Basic implementation
+
+```jsx
+import { Heading, Section } from '@carbon/react';
+
+function MyPage() {
+  return (
+    <Section>
+      <Heading>Main Title</Heading>
+      <p>Page content...</p>
+
+      <Section>
+        <Heading>Section Title</Heading>
+        <p>Section content...</p>
+      </Section>
+    </Section>
+  );
+}
+```
+
+### Semantic HTML with `as` prop
+
+```jsx
+<Section as="article">
+  <Heading>Article Title</Heading>
+  <p>Article content...</p>
+</Section>
+
+<Section as="nav">
+  <Heading>Navigation</Heading>
+  <ul>...</ul>
+</Section>
+```
+
+### Manual level override
+
+```jsx
+// Start at h3 instead of h1
+<Section level={3}>
+  <Heading>This renders as h3</Heading>
+  <Section>
+    <Heading>This renders as h4</Heading>
+  </Section>
+</Section>
+```
+
+### Reusable component pattern
+
+```jsx
+function Card({ title, description, children }) {
+  return (
+    <Section className="card">
+      <Heading>{title}</Heading>
+      <p>{description}</p>
+      {children}
+    </Section>
+  );
+}
+
+// Usage - heading level adapts to context
+<Section>
+  <Heading>Dashboard</Heading>
+  <Card title="Statistics" description="View your stats" />
+  <Card title="Activity" description="Recent activity">
+    <Card title="Today" description="Today's activity" />
+  </Card>
+</Section>;
+```

src/pages/components/heading/style.mdx

@@ -0,0 +1,77 @@
+---
+title: Heading
+description:
+  The Heading component automatically infers the appropriate heading level based
+  on the Section component, helping maintain proper document structure without
+  manual specification.
+tabs: ['Usage', 'Style', 'Code', 'Accessibility']
+---
+
+## Color
+
+Heading text color is inherited from Carbon's theme tokens:
+
+| Element | Property | Token           |
+| ------- | -------- | --------------- |
+| Text    | color    | `$text-primary` |
+
+For more on color usage, see
+[Typography overview](/elements/typography/overview).
+
+## Typography
+
+The Heading component renders semantic HTML elements (h1-h6) with default
+browser styling. Apply Carbon type tokens via `className` for visual styling
+independent of semantic level.
+
+For detailed information on type tokens and their usage, see
+[Type sets](/elements/typography/type-sets).
+
+### Applying type tokens
+
+To use type token classes like `cds--type-heading-05`, ensure you've included
+the Carbon type styles in your SCSS:
+
+```scss
+@use '@carbon/type';
+@include type.type-classes();
+```
+
+Then apply the class to your Heading component:
+
+```jsx
+<Heading className="cds--type-heading-05">
+  Visually styled as heading-05
+</Heading>
+```
+
+Learn more about applying type tokens in
+[Type sets](/elements/typography/type-sets).
+
+### Productive type tokens
+
+Fixed sizes for product interfaces:
+
+| Token        | Size (px/rem) | Weight         | Line-height (px/rem) |
+| ------------ | ------------- | -------------- | -------------------- |
+| `heading-01` | 14 / 0.875    | SemiBold / 600 | 18 / 1.125           |
+| `heading-02` | 16 / 1        | SemiBold / 600 | 22 / 1.375           |
+| `heading-03` | 20 / 1.25     | Regular / 400  | 28 / 1.75            |
+| `heading-04` | 28 / 1.75     | Regular / 400  | 36 / 2.25            |
+| `heading-05` | 32 / 2        | Regular / 400  | 40 / 2.5             |
+| `heading-06` | 42 / 2.625    | Light / 300    | 50 / 3.125           |
+| `heading-07` | 54 / 3.375    | Light / 300    | 64 / 4               |
+
+### Expressive type tokens
+
+Fluid sizes for responsive layouts:
+
+| Token              | Min (px/rem) | Max (px/rem) | Weight        |
+| ------------------ | ------------ | ------------ | ------------- |
+| `fluid-heading-03` | 20 / 1.25    | 24 / 1.5     | Regular / 400 |
+| `fluid-heading-04` | 28 / 1.75    | 32 / 2       | Regular / 400 |
+| `fluid-heading-05` | 32 / 2       | 40 / 2.5     | Regular / 400 |
+| `fluid-heading-06` | 42 / 2.625   | 54 / 3.375   | Light / 300   |
+
+For more on typography layout and spacing, see
+[Type basics](/elements/typography/type-basics).