diff --git a/docs/js/scenery-basics/path-basic-example.js b/docs/js/scenery-basics/path-basic-example.js
new file mode 100644
index 000000000..a38f32077
--- /dev/null
+++ b/docs/js/scenery-basics/path-basic-example.js
@@ -0,0 +1,38 @@
+import { createSandbox } from "/js/createSandbox.js";
+
+createSandbox( "path-basic-example", ( scene, stepEmitter, display ) => {
+ const box = ( () => {
+ /*START*/
+ const content = new HBox( {
+ spacing: 10,
+ children: [
+ // Rectangles are specified with x, y, width, height
+ new Rectangle( 0, 0, 50, 50, {
+ // fill is the "internal" color
+ fill: 'red',
+
+ // stroke color is applied on top, on the border of the shape
+ stroke: 'black',
+
+ // the width of the stroke can be controlled
+ lineWidth: 3
+ } ),
+ // Circles have a radius specified
+ new Circle( 25, { fill: 'green' } ),
+ // Lines are specified with x1, y1, x2, y2 (connecting two points)
+ new Line( 0, 0, 50, 50, {
+ stroke: 'blue',
+ lineWidth: 5,
+
+ // lineCap can be used to control the appearance of the
+ // ends of the line similarly, lineJoin can be used to
+ // control the appearance of any corners
+ lineCap: 'round'
+ } )
+ ]
+ } );
+ /*END*/
+ return content;
+ } )();
+ scene.addChild( box );
+} );
\ No newline at end of file
diff --git a/docs/js/scenery-basics/path-shape-example.js b/docs/js/scenery-basics/path-shape-example.js
new file mode 100644
index 000000000..633033fdd
--- /dev/null
+++ b/docs/js/scenery-basics/path-shape-example.js
@@ -0,0 +1,23 @@
+import { createSandbox } from "/js/createSandbox.js";
+
+createSandbox( "path-shape-example", ( scene, stepEmitter, display ) => {
+ const box = ( () => {
+ /*START*/
+ // Method calls on the Shape can be chained for convenience
+ const shape = new Shape()
+ .moveTo( 0, 0 ) // start at 0,0
+ .lineTo( 40, 40 ) // line from 0.0 to 40,40
+ .quadraticCurveTo( 80, 0, 40, -40 ) // cubic to 40,-40
+ .lineTo( 40, 0 ) // line from 40,-40 to 40,0
+ .close(); // close with a line from 40,0 to 0,0
+
+ const content = new Path( shape, {
+ fill: 'red',
+ stroke: 'black',
+ lineWidth: 2
+ } );
+ /*END*/
+ return content;
+ } )();
+ scene.addChild( box );
+} );
\ No newline at end of file
diff --git a/docs/js/scenery-basics/path-svg-example.js b/docs/js/scenery-basics/path-svg-example.js
new file mode 100644
index 000000000..1db88afed
--- /dev/null
+++ b/docs/js/scenery-basics/path-svg-example.js
@@ -0,0 +1,16 @@
+import { createSandbox } from "/js/createSandbox.js";
+
+createSandbox( "path-svg-example", ( scene, stepEmitter, display ) => {
+ const box = ( () => {
+ /*START*/
+ const shape = new Shape( 'M 0 0 L 40 40 Q 80 0 40 -40 L 40 0 L 0 0 Z' );
+ const content = new Path( shape, {
+ fill: 'cyan',
+ stroke: 'black',
+ lineWidth: 2
+ } );
+ /*END*/
+ return content;
+ } )();
+ scene.addChild( box );
+} );
\ No newline at end of file
diff --git a/docs/js/scenery-basics/text-basic-example.js b/docs/js/scenery-basics/text-basic-example.js
new file mode 100644
index 000000000..2bd1f8491
--- /dev/null
+++ b/docs/js/scenery-basics/text-basic-example.js
@@ -0,0 +1,14 @@
+import { createSandbox } from "/js/createSandbox.js";
+
+createSandbox( "text-basic-example", ( scene, stepEmitter, display ) => {
+ const box = ( () => {
+ /*START*/
+ const content = new Text( 'Lauren Ipsum, daughter of Dolor Sit Amet', {
+ fill: 'purple',
+ font: 'bold 20px Arial' // any CSS font property is valid
+ } );
+ /*END*/
+ return content;
+ } )();
+ scene.addChild( box );
+} );
\ No newline at end of file
diff --git a/docs/js/scenery-basics/text-property-example.js b/docs/js/scenery-basics/text-property-example.js
new file mode 100644
index 000000000..220187318
--- /dev/null
+++ b/docs/js/scenery-basics/text-property-example.js
@@ -0,0 +1,22 @@
+import { createSandbox } from "/js/createSandbox.js";
+
+createSandbox( "text-property-example", ( scene, stepEmitter, display ) => {
+ const box = ( () => {
+ /*START*/
+ const property = new StringProperty( 'Initial Text' );
+ const content = new Text( property, {
+ fill: 'purple',
+
+ // font properties can be specified independently
+ fontFamily: 'serif',
+ fontSize: 26,
+ fontStyle: 'italic'
+ } );
+
+ // change the text property
+ property.value = 'Different, serif text';
+ /*END*/
+ return content;
+ } )();
+ scene.addChild( box );
+} );
\ No newline at end of file
diff --git a/docs/learn/scenery-basics.md b/docs/learn/scenery-basics.md
index b840a0b67..25b8ac3df 100644
--- a/docs/learn/scenery-basics.md
+++ b/docs/learn/scenery-basics.md
@@ -78,6 +78,9 @@ or by using `mutate()`:
When using the declarative options syntax, the parameters are executed in an order such that anything that affects
the size of the node will be applied before anything that depends on the position of the node (e.g. `center`).
+Note that these approaches (declarative, or imperative setters) should function for all properties of the basic
+Scenery node types (e.g. [Text] `font`, [Path] `fill`, etc.)
+
## Children
Nodes can have children, which are other nodes that are positioned relative to their parent. The order of the children
@@ -99,31 +102,50 @@ and the ability to `removeChild()` or `insertChild()` exists for when you need t
## Paths
-Shapes are displayed with the [Path] subtype of [Node]. They are created from [Shape] objects, which represent
-the 2d shapes that can be rendered. The API is very similar to the
+Shapes are displayed with the [Path] subtype of [Node]. There are a number of flexible [Path] subtypes for common shapes:
+[Rectangle], [Circle], and [Line]. All [Path] types (along with anything [Paintable], like [Text]) can take fills, strokes, and
+other parameters that control their appearance.
+
+
+
+
+It is also possible to create custom shapes with the [Shape] object. The API is very similar to the
[CanvasRenderingContext2D](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D) API, where
-the path commands are used to define the [Shape], and the `fill`, `stroke`, and `lineWidth` properties are used to
-style the [Path].
+the path commands are used to define the [Shape]:
-TODO: example
+
+
-**Note**: The `fill` and `stroke` properties are examples of [Paintable] properties, which are also shared by [Text] nodes.
+[Path] objects can also be created with a SVG path string (see [documentation for the SVG path syntax](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d)):
-[Path] objects can also be created with a SVG path string (see [documentation for the SVG path syntax](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d):
+
+
-TODO: example
+To learn more about [Shape] objects, see the [Shape Guide](./shapes.md).
## Text
-Text is displayed with the [Text] subtype of [Node]. The text can be styled with the `font`, `fill`, and `stroke`.
+### Basic Text
+
+Basic text is displayed with the [Text] subtype of [Node]. The text can be styled with the `font`, `fill`, and `stroke`.
+
+
+
[Text] nodes take in either a `string` or a `TReadOnlyProperty` object (a [Property], [ReadOnlyProperty], or [TinyProperty] with a string value).
-They will dynamically update their displayed text when the Property changes.
+They will dynamically update their displayed text when the Property changes, to support dynamic and translated content:
-TODO: example
+
+
**Note**: Text is positioned so that the origin of the node is at the left baseline of the text.
+### Rich Text
+
+TODO: docs and examples
+
+-- include separators
+
## Images
Images can be displayed (with the upper-left corner at the origin of the node) with the [Image] subtype of [Node].
@@ -406,4 +428,4 @@ Visibility
Opacity
Clip area
Filters
-Renderer
\ No newline at end of file
+Renderer