primer · shawnbot · Jun 20, 2019 · Jun 5, 2019 · Jun 5, 2019 · Jun 5, 2019
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -50,7 +50,7 @@ Good pull requests—patches, improvements, new features—are a fantastic help.
 
 **Please ask first** before embarking on any significant pull request (e.g. implementing features, refactoring code, porting to a different language), otherwise you risk spending a lot of time working on something that the project's developers might not want to merge into the project.
 
-### Updating Primer CSS modules
+### Updating Primer CSS
 
 Anyone can open a pull request on Primer CSS. You do not need to work at GitHub or be a member of the org to open a pull request.
 

diff --git a/DEVELOP.md b/DEVELOP.md
@@ -46,26 +46,8 @@ Then visit http://localhost:3000/css to view the site.
 
 :rotating_light: **Warning:** Next.js has a [long-running issue](https://github.com/zeit/next.js/issues/1189) with trailing slashes in URLs. Avoid visiting `http://localhost:3000/` if possible, as this may cause your development server to fail in less-than-graceful ways.
 
-
-### Syncing the docs
-Both before and while the Next dev server runs, all of the Markdown files within the `src/` directory are synced to Next's `pages/` directory and rewritten to include useful metadata.
-
-If, for whatever reason, the dev server isn't syncing files from `src/` to `pages/`, you have two choices:
-
-1. Stop the server (`ctrl-C`) and restart it (`npm start`), which will re-sync the files and clear Next's cache.
-2. Run [script/sync](./script/sync) manually:
-
-    ```sh
-    # in the docs directory
-    script/sync
-    ```
-
-    **If you find yourself needing to do this often, please [file an issue](/primer/css/issues/new) and tag `@shawnbot`**. :bow:
-
 ### The pages directory
-The [pages directory](./pages/) contains all of the files that map to URLs on the site. Because we host the site at `primer.style/css` (and because of the way that Now's path aliasing feature works), we nest all of our documentation under the [css subdirectory](./pages/css).
-
-The sync task maintains a list of files copied from `src/` in `pages/css/.gitignore`, which ensures that none of these generated files are checked into git.
+The [pages directory](./pages/) contains all of the documentation files that map to URLs on the site. Because we host the site at `primer.style/css` (and because of the way that Now's path aliasing feature works), we nest all of our documentation under the [css subdirectory](./pages/css).
 
 
 ### URL tests
@@ -101,7 +83,6 @@ Our [`package.json`](package.json) houses a collection of [run-scripts] that we
 * `lint` lints all of our SCSS source files.
 * `lint-js` lints the docs site and supporting scripts.
 * `now-build` and `now-start` are run on [Now] to build and start the docs site server. `now-test` runs them both in order.
-* `sync` copies Markdown docs from `src/` to `pages/css/` and preps them for inclusion in the docs site.
 * `test-urls` compares a (pre-generated) list of paths from the [Primer Style Guide](https://styleguide.github.com/primer/) to files in `pages/css`, and lets us know if we've inadvertently deleted or renamed anything.
 * `test-migrate` tests the [`primer-migrate`](MIGRATING.md#primer-migrate) command line utility.
 * `watch` runs the sync script in watch mode, copying files as they're changed from `src/` to `pages/css/`.

diff --git a/pages/css/getting-started/contributing.md b/pages/css/getting-started/contributing.md
@@ -53,7 +53,7 @@ It's usually better to open an issue before investing time in spiking out a new
 
 ### Step 2: Design and build the new styles
 
-* You may want to explore the visual design for a new component before spiking it out in code. If so, continue in the issue and post your design mockups. Using the [Jekyll prototyping tool](https://github.com/github/design/blob/master/docs/resources/prototyping.md#jekyll) could also be a good option, it pulls in the production CSS so you can explore options in isolation before jumping into production code.
+* You may want to explore the visual design for a new component before spiking it out in code. If so, continue in the issue and post your design mockups. Using our [CodePen template](https://codepen.io/team/GitHub/pen/xYLdZd) could also be a good option, it pulls in Primer CSS so you can explore options in isolation before jumping into production code.
 * When you're ready, spike out a branch and build out your new component, object, or utilities according to the style guide principles, ensuring you follow our naming convention for each of the styles.
 * Refactor parts of the product where you think those new styles could be used to test they work for each use case. This does not mean for every instance, but enough of the key use cases to be sure the styles are flexible enough. To avoid blowing out your initial pull request we recommend you do larger amounts of refactoring in an additional branch.
 * When you're ready for review, add the `status: review needed` and the `design-systems` labels to your pull request. Follow the [ship checklist](#ship-checklist) for additional shipping steps.
@@ -93,9 +93,9 @@ bundle: alerts
 
 ```
 
-### Anatomy of a guide
+### Documentation Anatomy
 
-The anatomy of a style guide markdown file pretty straight forward, but has a few optional properties for making the page render special features.
+The anatomy of a Primer CSS markdown file is pretty straight forward, but has a few optional properties for making the page render special features.
 
 Typically the file will look something like this:
 
@@ -180,83 +180,6 @@ When using code blocks for demo purposes, you can choose to render each of the b
   ```
 ```
 
-## Primer CSS modules
-
-Modules are created for all the styles we include in the Primer framework. Modules are folders with a specific structure that include CSS, a `package.json`, and other files for publishing to repositories in our GitHub Primer organization and NPM.
-
-The source of truth for our CSS will be in the github/github codebase, but we publish updates to NPM whenever styles in github/github are changed. By publishing to NPM we are able to distribute our reusable modules to other GitHub properties.
-
-Modules are grouped into three packages:
-- **primer-core:** modules that are used for dotcom as well as marketing websites
-- **primer-product:** modules that are only used on dotcom
-- **primer-marketing:** modules that are only used on marketing websites and occasionally for promotional content on dotcom
-
-You can add module packages by including any or all of the following imports in your bundle:
-```
-@import "primer-core/index.scss"
-@import "primer-product/index.scss"
-@import "primer-marketing/index.scss"
-```
-
-### Creating a module
-
-1. Create a new repository on https://github.com/primer that will be the location for your module. Only the design systems team have write access to that repository. If you don't have access, ask in #design-systems and someone will create a folder for you.
-2. Create a new folder inside one of the primer directories (core, product, or marketing), and within the appropriate styles folder (components, objects, utilities etc.). This folder cannot be inside another module with a `package.json` file.
-3. Inside the folder you'll need at least a `package.json` file. Here is an example of what you'll need in the package file. The main thing it's looking for are `name, version, and repository`. The publish script uses this to push to the distribution repository.
-
-    ```js
-    {
-      "name": "module-name",
-      "version": "0.1.0",
-      "description": "",
-      "homepage": "https://github.com/styleguide",
-      "license": "MIT",
-      "repository": "https://github.com/primer/primer.git",
-      "main": "utilities.scss",
-      "bugs": {
-        "url": "https://github.com/primer/primer/issues"
-      },
-      "author": "GitHub, Inc.",
-      "scripts": {
-        "test": "echo \"Error: no test specified\" && exit 1"
-      },
-      "keywords": [
-        "primer",
-        "css",
-        "github",
-        "primercss"
-      ]
-    }
-    ```
-
-5. The directory layout should typically be like this:
-
-    ```
-    a-module/
-      ├── lib/
-      │   ├── partial.scss
-      │   └── partial.scss
-      ├── index.scss
-      ├── README.md
-      └── package.json
-    ```
-
-    Create a stylesheet named `index.scss`. In this file include a list of relative imports for the partials required, like the example below:
-
-    ```scss
-    @import "primer-support/index.scss";
-    @import "./lib/button.scss";
-    @import "./lib/button-group.scss";
-    ```
-
-    Add a `README` to give some info on the module and how to install it, and a documentation section. Here's an example of the [buttons README](https://github.com/primer/primer/blob/master/README.md).
-
-### Publishing changes and new modules
-
-Once you have your directory setup, you will be ready to publish the module.
-
-To publish, there are two requirements. First, you must be on the `master` branch. Second, all changes should be committed and synced with the remote `master`. These requirements protect us from changes being overwritten. Once you're on `master` run `script/css-modules --help` to get a list of all the available commands. This script will help with versioning and publishing.
-
 #### Versioning
 
 Primer CSS follows [semantic versioning](http://semver.org/) conventions. This helps others know when a change is a patch, minor, or breaking change.

diff --git a/pages/css/getting-started/index.md b/pages/css/getting-started/index.md
@@ -25,6 +25,19 @@ Install the Primer CSS npm package modules by running `npm install @primer/css`.
 npm install @primer/css --save
 ```
 
+### Paths
+Here's what you need to know about how the files are structured in both git and in the published npm module:
+
+* In git, all of the SCSS source files live in the `src/` directory.
+* When published, all of the files in `src/` are "hoisted" to the package root so that you can import, say, utilities with:
+
+    ```scss
+    @import "@primer/css/utilities/index.scss";
+    ```
+
+* All bundle interdependencies within Primer CSS are defined as relative imports (e.g. with `../`), so everything should work fine as long as the `@primer/css` directory is in one of your Sass include paths (i.e. `node_modules`).
+
+
 ### For a Jekyll site
 
 Make sure you have [Jekyll](https://jekyllrb.com/) version `3.3.1` or greater with:

diff --git a/pages/css/index.md b/pages/css/index.md
@@ -47,30 +47,18 @@ Primer CSS is built upon systems that form the foundation of our styles such as
 
 <PrimitivesOverview />
 
-## Primer CSS bundles
-
-Each component or group of styles is distributed via npm as a separate CSS file, or "bundle". We also distribute "meta-packages" for core (shared) elements, product-specific (github.com) styles, and marketing.
-
-<PrimerPackageBox meta={bundles.primer} count={Object.keys(bundles).length - 1} mb={4} />
-
-<Flex justifyContent="space-around" mb={6}>
-  <MetaPackageBox title="Core" meta={bundles.core} width={1/3}>
-    The core bundle contains styles that are shared between GitHub product and marketing websites.
-  </MetaPackageBox>
-  <MetaPackageBox title="Product" meta={bundles.product} width={1/3}>
-    The product bundle contains styles that are used on GitHub product websites.
-  </MetaPackageBox>
-  <MetaPackageBox title="Marketing" meta={bundles.marketing} width={1/3}>
-    The marketing bundle contains styles that are used on GitHub marketing websites.
-  </MetaPackageBox>
-</Flex>
+## Structure
+Primer CSS is published to [npm] as [@primer/css]. Each of Primer CSS's "modules" lives in a subfolder under `src/` with an `index.scss` in it. Generally speaking, the styles are divided into three primary themes:
 
+* **Core** styles (in `core/`) are common dependencies, which include support variables, native element and typography styles, buttons, navigation, tooltips, etc.
+* **Product** styles (in `product/`) are specific to github.com, and include components such as avatars, labels, markdown styles, popovers, and progress indicators.
+* **Marketing** styles (in `marketing/`) are specific to GitHub marketing efforts, including international and event-focused sites as well as the more design-heavy feature pages on github.com. Marketing styles include new colors and button styles, and extend the core typography and whitespace scales.
 
 <div class="bg-gray py-6">
   <div class="d-flex flex-wrap flex-md-nowrap px-6 gutter-lg">
     <div class="col-12 col-md-9 pr-0 pr-lg-2">
       <h3 class="f3 text-normal m-0">Use Primer CSS in your project</h3>
-      <p class="my-3">Pick and choose what you need. Install the entire Primer CSS bundle or individual packages via npm.</p>
+      <p class="my-3">Pick and choose what you need. Install the entire Primer CSS bundle or import individual folders.</p>
       <a href="/css/getting-started" class="btn btn-outline">Installation instructions</a>
     </div>
   </div>