Document @forward

source/documentation/at-rules/forward.html.md.erb

@@ -1,7 +1,181 @@
 ---
 title: "@forward"
 introduction: >
-  TODO(nweiz): Write this
+  The `@forward` rule loads a Sass stylesheet and makes its [mixins](mixin),
+  [functions](function), and [variables](../variables) available when your
+  stylesheet is loaded with the [`@use` rule](use). It makes it possible to
+  organize Sass libraries across many files, while allowing their users to load
+  a single entrypoint file.
 ---
 
+The rule is written `@forward "<url>"`. It loads the module at the given URL
+just like `@use`, but it makes the [public][] members of the loaded module
+available to users of your module as though they were defined directly in your
+module. Those members aren't available in your module, though—if you want that,
+you'll need to write a `@use` rule as well. Don't worry, it'll only load the
+module once!
+
+[public]: use#private-members
+
+<% fun_fact do %>
+  The `@forward` rule acts just like `@use` when it comes to a module's CSS.
+  Styles from a forwarded module will be included in the compiled CSS output,
+  and the module with the `@forward` can [extend][] it, even if it isn't also
+  `@use`d.
+
+  [extend]: extend
+<% end %>
+
+<% example do %>
+  // src/_list.scss
+  @mixin list-reset {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  ---
+  // bootstrap.scss
+  @forward "src/list";
+  ---
+  // styles.scss
+  @use "bootstrap";
+
+  li {
+    @include bootstrap.list-reset;
+  }
+  ===
+  // src/_list.sass
+  @mixin list-reset
+    margin: 0
+    padding: 0
+    list-style: none
+  ---
+  // bootstrap.sass
+  @forward "src/list"
+  ---
+  // styles.sass
+  @use "bootstrap"
+
+  li
+    @include bootstrap.list-reset
+  ===
+  li {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+<% end %>
+
+## Adding a Prefix
+
+Because module members are usually used with [a namespace][], short and simple
+names are usually the most readable option. But those names might not make sense
+outside the module they're defined in, so `@forward` has the option of adding an
+extra prefix to all the members it forwards.
+
+This is written `@forward "<url>" as <prefix>-*`, and it adds the given prefix
+to the beginning of every mixin, function, and variable name forwarded by the
+module. For example, if the module defines a member named `reset` and it's
+forwarded `as list-*`, downstream stylesheets will refer to it as `list-reset`.
+
+[a namespace]: use#loading-members
+
+<% example do %>
+  // src/_list.scss
+  @mixin reset {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  ---
+  // bootstrap.scss
+  @forward "src/list" as list-*;
+  ---
+  // styles.scss
+  @use "bootstrap";
+
+  li {
+    @include bootstrap.list-reset;
+  }
+  ===
+  // src/_list.sass
+  @mixin reset
+    margin: 0
+    padding: 0
+    list-style: none
+  ---
+  // bootstrap.sass
+  @forward "src/list" as list-*
+  ---
+  // styles.sass
+  @use "bootstrap"
+
+  li
+    @include bootstrap.list-reset
+  ===
+  li {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+<% end %>
+
 ## Controlling Visibility
+
+Sometimes, you don't want to forward *every* member from a module. You may want
+to keep some members private so that only your package can use them, or you may
+want to require your users to load some members a different way. You can control
+exactly which members get forwarded by writing `@forward "<url>" hide
+<members...>` or `@forward "<url>" show <members...>`.
+
+The `hide` form means that the listed members shouldn't be forwarded, but
+everything else should. The `show` form means that *only* the named members
+should be forwarded. In both forms, you list the names of mixins, functions, or
+variables (including the `$`).
+
+<% example(autogen_css: false) do %>
+  // src/_list.scss
+  $horizontal-list-gap: 2em;
+
+  @mixin list-reset {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  @mixin list-horizontal {
+    @include reset;
+
+    li {
+      display: inline-block;
+      margin: {
+        left: -2px;
+        right: $horizontal-list-gap;
+      }
+    }
+  }
+  ---
+  // bootstrap.scss
+  @forward "src/list" hide list-reset, $horizontal-list-gap;
+  ===
+  // src/_list.sass
+  $horizontal-list-gap: 2em
+
+  @mixin list-reset
+    margin: 0
+    padding: 0
+    list-style: none
+
+
+  @mixin list-horizontal
+    @include reset
+
+    li
+      display: inline-block
+      margin:
+        left: -2px
+        right: $horizontal-list-gap
+  ---
+  // bootstrap.sass
+  @forward "src/list" hide list-reset, $horizontal-list-gap
+<% end %>