CSS Module page: CSS Shapes (#33809)

* Draft: new guide: aspect-ratio

* add use cases

* current status

* new guide: aspect ratio

* borked repo

* Draft: shapes module landing page

* edit basic shape guide

* update to intro

* revert guide

* finish module landing page.

* finish module landing page.

* Apply suggestions from code review

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* flaw fix

* Apply suggestions from code review

Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

* Update files/en-us/web/css/css_shapes/index.md

Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

* Update files/en-us/web/css/css_shapes/basic_shapes/index.md

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

files/en-us/web/css/css_shapes/basic_shapes/index.md

@@ -138,4 +138,4 @@ You may well find the Firefox Shape Inspector very useful here to create your po
 
 ![The polygon basic shape, highlighted with the Shapes Inspector.](shapes-polygon.png)
 
-Another useful resource is [Clippy](https://bennettfeely.com/clippy/) - a tool for creating shapes for `clip-path`, as the values for Basic Shapes are the same as those used for `clip-path`.
+Another resource is [Clippy](https://bennettfeely.com/clippy/), a tool for creating shapes with examples using the CSS {{cssxref("clip-path")}} property, which uses the same basic shape functions and values as the `shape-outside` property.

files/en-us/web/css/css_shapes/index.md

@@ -2,14 +2,20 @@
 title: CSS shapes
 slug: Web/CSS/CSS_shapes
 page-type: css-module
-spec-urls: https://drafts.csswg.org/css-shapes/
+spec-urls:
+  - https://drafts.csswg.org/css-shapes-1/
+  - https://drafts.csswg.org/css-shapes-2/
 ---
 
 {{CSSRef}}
 
-The **CSS shapes** module describes geometric shapes that can be in CSS. For the [Level 1 specification](https://drafts.csswg.org/css-shapes/), CSS shapes can be applied to floating elements. The specification defines a number of different ways to define a shape on a floated element, causing wrapping lines to wrap round the shape rather than following the rectangle of the element's box.
+The **CSS shapes** module describes geometric shapes. It also defines CSS properties that can use the shapes to control the geometry of an element's float area; this area can then be applied to exclusions, or specify an element's content area.
 
-## Basic example
+The specification defines several ways to create shapes. Content can be wrapped around or within a shape rather than following the default rectangle shape of the element's box.
+
+Shapes define geometries that can be used as CSS values. This module provides functions for creating ellipses, polygons, and arbitrary geometries. Other CSS modules can make use of shapes defined in this specification, including [CSS motion path](/en-US/docs/Web/CSS/CSS_motion_path) and [CSS masking](/en-US/docs/Web/CSS/CSS_masking).
+
+## CSS shapes in action
 
 The example below shows an image that has been floated left, and the `shape-outside` property applied with a value of `circle(50%)`. This creates a circle shape, and the content wrapping the float now wraps around that shape. This changes the length of the wrapping text's line boxes.
 
@@ -23,28 +29,84 @@ The example below shows an image that has been floated left, and the `shape-outs
 - {{cssxref("shape-margin")}}
 - {{cssxref("shape-outside")}}
 
+> **Note:** The CSS shapes module introduces the `shape-inside` and `shape-padding` properties that have not yet been implemented.
+
 ### Data types
 
 - {{cssxref("<basic-shape>")}}
 
+### Functions
+
+- {{cssxref("basic-shape/circle","circle()")}}
+- {{cssxref("basic-shape/ellipse","ellipse()")}}
+- {{cssxref("basic-shape/inset","inset()")}}
+- {{cssxref("basic-shape/path","path()")}}
+- {{cssxref("basic-shape/polygon","polygon()")}}
+- {{cssxref("basic-shape/rect","rect()")}}
+- {{cssxref("basic-shape/shape","shape()")}}
+- {{cssxref("basic-shape/xywh","xywh()")}}
+
+### Terms
+
+- [Reference box](/en-US/docs/Web/CSS/CSS_shapes/Basic_shapes#the_reference_box)
+
 ## Guides
 
 - [Overview of shapes](/en-US/docs/Web/CSS/CSS_shapes/Overview_of_shapes)
+
+  - : Defining basic shapes with the `shape-margin` and `clip-path` properties, and debugging basic shapes with
+    Developer Tools.
+
 - [Shapes from box values](/en-US/docs/Web/CSS/CSS_shapes/From_box_values)
-- [Basic shapes](/en-US/docs/Web/CSS/CSS_shapes/Basic_shapes)
+
+  - : Using `border-radius` curvatures and CSS box model values to create shapes.
+
+- [Basic shapes with `shape-outside`](/en-US/docs/Web/CSS/CSS_shapes/Basic_shapes)
+
+  - : Creating rectangles, circles, ellipses, and polygons with CSS shapes, the reference box, and the `shape-outside` property.
+
 - [Shapes from images](/en-US/docs/Web/CSS/CSS_shapes/Shapes_from_images)
 
+  - : Creating shapes from semi-transparent image files and CSS Gradients.
+
+## Related concepts
+
+[CSS motion path](/en-US/docs/Web/CSS/CSS_motion_path) module
+
+- {{cssxref("offset")}}
+- {{cssxref("offset-anchor")}}
+- {{cssxref("offset-distance")}}
+- {{cssxref("offset-path")}}
+- {{cssxref("offset-position")}}
+- {{cssxref("offset-rotate")}}
+- {{cssxref("ray")}} function
+
+[CSS masking](/en-US/docs/Web/CSS/CSS_masking) module
+
+- {{cssxref("clip")}}
+- {{cssxref("clip-path")}}
+- {{SVGAttr("clip-rule")}}
+- {{cssxref("mask")}}
+- {{cssxref("mask-origin")}}
+- {{cssxref("mask-position")}}
+
+[CSS backgrounds and borders](/en-US/docs/Web/CSS/CSS_backgrounds_and_borders) module
+
+- {{cssxref("border-radius")}} shorthand
+
+[CSS box model](/en-US/docs/Web/CSS/CSS_box_model) module
+
+- {{cssxref("box-edge")}} data type
+
 ## Specifications
 
 {{Specifications}}
 
 ## See also
 
 - [CSS Shapes resources](https://codepen.io/KristopherVanSant/post/css-shapes-resources)
-- [CSS Shapes 101](https://alistapart.com/article/css-shapes-101/)
-- [Creating non-rectangular layouts with CSS Shapes](https://www.sarasoueidan.com/blog/css-shapes/)
-- [How to use CSS Shapes in your web design](https://webdesign.tutsplus.com/tutorials/how-to-use-css-shapes-in-your-web-design--cms-27498)
-- [How to get started with CSS Shapes](https://www.webdesignerdepot.com/2015/03/how-to-get-started-with-css-shapes/)
-- [What I learned in one weekend with CSS Shapes](https://medium.com/@MHarreither/what-i-learned-in-one-weekend-with-css-shapes-66ae9be69cc5)
-- [CSS vs. SVG: Shapes and arbitrarily-shaped UI components](https://blog.adobe.com/en/publish/2015/09/01/css-vs-svg-shapes-and-arbitrarily-shaped-ui-components)
-- [Edit shape paths in CSS — Firefox Developer Tools](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/edit_css_shapes/index.html)
+- [CSS Shapes 101](https://alistapart.com/article/css-shapes-101/) via alistapart.com (2014)
+- [Creating non-rectangular layouts with CSS Shapes](https://www.sarasoueidan.com/blog/css-shapes/) via sarasoueidan.com (2013)
+- [How to use CSS Shapes in your web design](https://webdesign.tutsplus.com/tutorials/how-to-use-css-shapes-in-your-web-design--cms-27498) via tutsplus.com (2016)
+- [How to get started with CSS Shapes](https://www.webdesignerdepot.com/2015/03/how-to-get-started-with-css-shapes/) via webdesignerdepot.com (2015)
+- [Edit CSS shapes with the shape path editor](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/edit_css_shapes/index.html) via mozilla.org (2018) ([Video](https://www.youtube.com/watch?v=u9bDe3Bw0sA))