From 6bdd1c4c0ea567c45fdecb1e858a99ee5da246ad Mon Sep 17 00:00:00 2001 From: amzrk2 Date: Mon, 13 Apr 2020 19:13:39 +0800 Subject: Initial commit --- assets/sass/@primer/css/DEVELOP.md | 97 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 assets/sass/@primer/css/DEVELOP.md (limited to 'assets/sass/@primer/css/DEVELOP.md') diff --git a/assets/sass/@primer/css/DEVELOP.md b/assets/sass/@primer/css/DEVELOP.md new file mode 100644 index 0000000..09c77ed --- /dev/null +++ b/assets/sass/@primer/css/DEVELOP.md @@ -0,0 +1,97 @@ +# Primer CSS Development + +If you've made it this far, **thank you**! We appreciate your contribution, and hope that this document helps you along the way. If you have any questions or problems, don't hesitate to [file an issue](https://github.com/primer/css/issues/new). + +## 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. + +### 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`). + + +## Workflow +The typical Primer workflow looks something like this: + +1. `npm install` to install the development dependencies. +1. [Start Storybook](#storybook) +1. Navigate to the module you're working on and modify the SCSS and/or markdown files. +1. Test your changes in Storybook. +1. Push your work to a new branch. +1. Request a review from one of the Primer "core" team members. + +## Install +Run `npm install` to install the npm dependencies. + +## Docs site +The Primer CSS docs are built with React using [Doctocat](https://primer.style/doctocat) and automatically deployed on every push to this repo with [Now]. You can run the server locally with: + +```sh +npm start +``` + +Then visit http://localhost:8000 to view the site. + +### The docs directory +The [docs directory](./docs/) contains all of the documentation files in our docs site. Files are nested in the `/content` folder. + + +### URL tests +We have a script that catches inadvertent URL changes caused by renaming or deleting Markdown docs: + +```sh +npm run test-urls +``` + +This script includes some exceptions for URLs that have been intentionally moved or removed in the process of moving away from the [GitHub Style Guide](https://styleguide.github.com/primer/), and which you will need to modify if you rename or remove either Markdown docs or their `path` frontmatter. See [#641](https://github.com/primer/css/pull/641) for more information. + +## Storybook +To borrow a [metaphor from Brad Frost](http://bradfrost.com/blog/post/the-workshop-and-the-storefront/), the [docs site](#docs-site) is Primer CSS's storefront, and [Storybook] is its workshop. + +Our Storybook setup allows you to view every HTML code block in Primer CSS's Markdown docs in isolation. To get started, run the Storybook server with: + +```sh +npm run start-storybook +``` + +This should open up the site in your browser (if not, navigate to `http://localhost:8001`). + +### Code blocks +All `html` fenced code blocks in `src/**/*.md` will be rendered as stories and listed under the relevant module's name in the left-hand nav. File changes should trigger a live reload automatically (after a brief delay). + + +## Scripts +Our [`package.json`](package.json) houses a collection of [run-scripts] that we use to maintain, test, build, and publish Primer CSS. Run `npm run