docs: draft proposal for improving structure clarity

src/data/nav-items.yaml

@@ -1,4 +1,4 @@
-- title: All about Carbon
+- title: Introduction
   pages:
     - title: What is Carbon?
       path: /all-about-carbon/what-is-carbon/
@@ -27,7 +27,7 @@
   pages:
     - title: Get started
       path: /developing/get-started/
-    - title: Frameworks
+    - title: Official frameworks
       path: /developing/frameworks/react/
     - title: Community frameworks
       path: /developing/community-frameworks/angular/
@@ -47,7 +47,7 @@
       path: /contributing/component-checklist/
     - title: Documentation
       path: /contributing/documentation/
-- title: Migrating
+- title: Upgrading versions
   pages:
     - title: Guide
       path: /migrating/guide/overview/

src/pages/developing/get-started.mdx

@@ -38,9 +38,74 @@ In [Developer resources](/developing/dev-resources/resources/), you’ll find
 Carbon tools, as well as our GitHub repos and Storybooks for your framework of
 choice.
 
-## Additional guidance
+### Learn the basic concepts of Carbon
 
-### Take a tutorial
+The [introduction section](/all-about-carbon/what-is-carbon/) will help making
+sense of how Carbon is built and why.
+
+#### Learn about the IBM Design Language
+
+Carbon expresses the [IBM Design Language](https://www.ibm.com/design/language/)
+in product and delivers it through tools for designers and developers including
+guidance, tooling, components, and support. Take the time to read the site so
+that you fully understand what drives IBM’s design philosophy and principles,
+and can make informed decisions in your product work.
+
+<InlineNotification kind="warning">
+Understanding the concepts of the IBM Design Language will save you lots
+of unnecessary code (especially CSS), will make your implementation faster
+to implement and faster to upgrade. Don't skip this step.
+</InlineNotification>
+
+#### Learn how Carbon implements the IBM Design Language
+
+The elements are essential to know for using Carbon right.
+
+<CardGroup>
+  <MiniCard
+    title="2x Grid"
+    href="/elements/2x-grid/overview/"
+    actionIcon="arrowRight"
+    />
+  <MiniCard
+    title="Color"
+    href="/elements/color/overview/"
+    actionIcon="arrowRight"
+    />
+  <MiniCard
+    title="Icons"
+    href="/elements/icons/library/"
+    actionIcon="arrowRight"
+    />
+  <MiniCard
+    title="Pictograms"
+    href="/elements/pictograms/library/"
+    actionIcon="arrowRight"
+    />
+  <MiniCard
+    title="Motion"
+    href="/elements/motion/overview/"
+    actionIcon="arrowRight"
+    />
+  <MiniCard
+    title="Spacing"
+    href="/elements/spacing/overview/"
+    actionIcon="arrowRight"
+    />
+  <MiniCard
+    title="Themes"
+    href="/elements/themes/overview/"
+    actionIcon="arrowRight"
+    />
+  <MiniCard
+    title="Typography"
+    href="/elements/typography/overview/"
+    actionIcon="arrowRight"
+    />
+</CardGroup>
+
+
+## Take a tutorial
 
 We offer tutorials in React using Next.js, with community contributed tutorials
 for Angular and Vue, to guide you in creating an app with the Carbon Design
@@ -91,14 +156,6 @@ introduce web development best practices along the way.
 </Column>
 </Row>
 
-### Learn about the IBM Design Language
-
-Carbon expresses the [IBM Design Language](https://www.ibm.com/design/language/)
-in product and delivers it through tools for designers and developers including
-guidance, tooling, components, and support. Take the time to read the site so
-that you fully understand what drives IBM’s design philosophy and principles,
-and can make informed decisions in your product work.
-
 ## Connect with us
 
 ### Join us and the Carbon community

src/pages/elements/2x-grid/code.mdx

@@ -60,6 +60,12 @@ column widths by breakpoint, based on a 16 column grid.
   </Column>
 </Row>
 
+<InlineNotification kind="warning">
+The Carbon grid should be the main tool to place elements on the screen.
+If you use it right, you will need much less custom CSS like `display: flex`
+or playing with `position` and size settings.
+</InlineNotification>
+
 ### AspectRatio
 
 When designing fluid layouts, it’s helpful for an asset or card to be a specific

src/pages/index.mdx

@@ -1,6 +1,35 @@
 import HomepageTemplate from '../components/Homepage.js';
+import { Tag } from '@carbon/react';
+
 export default HomepageTemplate;
 
+### New to Carbon?
+
+Check our [introduction to Carbon](/all-about-carbon/what-is-carbon/) first:
+
+<Row className="resource-card-group-3-across">
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+    subTitle="What is Carbon?"
+    href="/all-about-carbon/what-is-carbon/"
+    actionIcon="arrowRight"
+    >
+      <MdxIcon name="carbon" />
+  </ResourceCard>
+</Column>
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+    subTitle="The Carbon ecosystem"
+    href="/all-about-carbon/the-carbon-ecosystem/"
+    actionIcon="arrowRight"
+    >
+      <MdxIcon name="carbon" />
+  </ResourceCard>
+</Column>
+</Row>
+
+### Get started
+
 <Row className="image-card-group">
 <Column colMd={4} colLg={4} noGutterSm>
 
@@ -33,25 +62,102 @@ export default HomepageTemplate;
 </Column>
 <Column colMd={4} colLg={4} noGutterSm>
       <ImageCard
-      title="Migrate"
+      title="Upgrade"
       aspectRatio="1:1"
       href="https://carbondesignsystem.com/migrating/guide/overview/"
       actionIcon="arrowRight"
       titleColor="dark"
       iconColor="dark"
       >
 
-![Migrate](/homepage/images/homepage-migration.png)
+![Upgrade](/homepage/images/homepage-migration.png)
 
   </ImageCard>
 </Column>
 </Row>
 
+### Ecosystem and libraries
+
+Looking for a component that you saw in a design or product but can't
+find it inside Carbon core? Check those libraries for extended
+use cases – complex components, patterns, guidelines for navigation and more.
+
+Carbon is modular to cater to thousands of developers and projects.
+That means that Carbon is composed of multiple libraries that build an ecosystem.
+
+It is likely most projects will involve Carbon core and at least
+one of those extensions.
+
+<Row className="resource-card-group-3-across">
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+    title="Carbon for IBM Products"
+    href="http://ibm.biz/carbon4ibmproducts"
+    >
+      <MdxIcon name="carbon" />
+      <Tag type="blue">IBMers only</Tag>
+  </ResourceCard>
+</Column>
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+    title="Carbon for Cloud"
+    href="https://ibm.biz/carbon4cloud"
+    >
+      <MdxIcon name="carbon" />
+      <Tag type="blue">IBMers only</Tag>
+  </ResourceCard>
+</Column>
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+    title="Carbon for IBM.com"
+    href="https://www.ibm.com/standards/carbon/"
+    >
+      <MdxIcon name="carbon" />
+  </ResourceCard>
+</Column>
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+    subTitle="Community-driven submissions"
+    title="Carbon labs"
+    href="https://labs.carbondesignsystem.com/"
+    >
+      <MdxIcon name="github" />
+  </ResourceCard>
+</Column>
+</Row>
+
+The structure of the Carbon documentation follows the following rules.
+Each Carbon library has:
+
+<Row>
+<Column colMd={5} colLg={8}>
+1. **A main website**, like this one for Carbon core, linking the main sources
+together and providing a starting point for documentation for both designers
+and developers.
+1. **A Storybook instance** for each library implementation, so developers
+can learn about the code requirements and the component APIs. The designers
+can also use Storybook to first inquire about limitations and capabilities
+of components.
+1. Detailed understanding, or debugging, or Carbon code, might need source
+access. By having a **GitHub repository per library**, Carbon offers full visibility
+to developers as well as the possibility to report bugs and general issues.
+</Column>
+<Column colMd={2} colLg={3} offsetMd={1} offsetLg={1}>
+  <Aside>
+
+[Storybook](https://storybook.js.org) is an open source software for documenting and cataloguing front-end components.
+
+  </Aside>
+</Column>
+</Row>
+
 ### Other resources
 
 The component libraries give developers a collection of reusable components for
 building websites and user interfaces.
 
+#### Design toolkits
+
 <Row className="resource-card-group-3-across">
 <Column colLg={4} colMd={4} noGutterSm>
   <ResourceCard
@@ -60,7 +166,7 @@ building websites and user interfaces.
     >
       <MdxIcon name="figma" />
   </ResourceCard>
-</Column>  
+</Column>
 <Column colLg={4} colMd={4} noGutterSm>
   <ResourceCard
     subTitle="Sketch kits"
@@ -69,51 +175,54 @@ building websites and user interfaces.
       <MdxIcon name="sketch" />
   </ResourceCard>
 </Column>
+</Row>
+
+#### Code repositories
+
+<Row className="resource-card-group-3-across">
 <Column colLg={4} colMd={4} noGutterSm>
   <ResourceCard
-    subTitle="Carbon React components"
+    subTitle="Carbon core React components"
     href="https://github.com/carbon-design-system/carbon/tree/main/packages/react"
     >
-
-<MdxIcon name="github" />
-
+      <MdxIcon name="github" />
+      <Tag type="blue">Official</Tag>
   </ResourceCard>
 </Column>
 <Column colLg={4} colMd={4} noGutterSm>
   <ResourceCard
-    subTitle="Carbon Angular components"
-    href="https://github.com/IBM/carbon-components-angular"
+    subTitle="Carbon core Web Components"
+    href="https://github.com/carbon-design-system/carbon/tree/main/packages/web-components"
     >
-
-<MdxIcon name="github" />
-
+      <MdxIcon name="github" />
+      <Tag type="blue">Official</Tag>
   </ResourceCard>
 </Column>
 <Column colLg={4} colMd={4} noGutterSm>
   <ResourceCard
-    subTitle="Carbon Vue components"
-    href="https://github.com/carbon-design-system/carbon-components-vue"
+    subTitle="Carbon core Angular components"
+    href="https://github.com/IBM/carbon-components-angular"
     >
-
-<MdxIcon name="github" />
-
+      <MdxIcon name="github" />
+      <Tag type="green">Community</Tag>
   </ResourceCard>
 </Column>
 <Column colLg={4} colMd={4} noGutterSm>
   <ResourceCard
-    subTitle="Carbon Svelte components"
-    href="https://github.com/IBM/carbon-components-svelte"
+    subTitle="Carbon core Vue components"
+    href="https://github.com/carbon-design-system/carbon-components-vue"
     >
-    <MdxIcon name="github" />
+      <MdxIcon name="github" />
+      <Tag type="green">Community</Tag>
   </ResourceCard>
 </Column>
-
 <Column colLg={4} colMd={4} noGutterSm>
   <ResourceCard
-    subTitle="Carbon Web Components"
-    href="https://github.com/carbon-design-system/carbon/tree/main/packages/web-components"
+    subTitle="Carbon core Svelte components"
+    href="https://github.com/IBM/carbon-components-svelte"
     >
-    <MdxIcon name="github" />
+      <MdxIcon name="github" />
+      <Tag type="green">Community</Tag>
   </ResourceCard>
 </Column>
 </Row>