primer/blueprints

Reusable components for our documentation sites

Primer CSS

The CSS implementation of GitHub's Primer Design System

Documentation

⚠️ The documentation of this repo is not maintained anymore. Please raise any documentation-specific pull requests in primer.style/design

Our documentation site lives at primer.style/css. You'll be able to find detailed documentation on getting started, all of the components, our theme, our principles, and more.

Install

This repository is distributed with npm. After installing npm, you can install @primer/css with this command:

npm install --save @primer/css

Usage

The included source files are written in Sass using SCSS syntax. After installing with npm, you can add your project's node_modules directory to your Sass include paths (AKA load paths in Ruby), then import it like this:

@import "@primer/css/index.scss";

You can import individual Primer modules directly from the @primer/css package:

@import "@primer/css/core/index.scss";
@import "@primer/css/product/index.scss";
@import "@primer/css/marketing/index.scss";

Development

See DEVELOP.md for development docs.

Releasing (for GitHub staff)

You can find docs about our release process in RELEASING.md.

License

MIT © GitHub

blueprints's Issues

Add edit link component

Add an edit link component!

Support for custom elements

It seems that when using custom elements in code examples, the class attribute gets turned into JSX's classname.

Steps to reproduce

1. Add the following code example:

  ```html
    <custom-element class="btn">Button</custom-element>
  ```

Expected output

<custom-element class="btn">Button</custom-element>

Actual output

<custom-element classname="btn">Button</custom-element>

Hero Illustration

I'd love to get a hero illustration made for the docs site, as this is the only docs site that currently doesn't have one!

cc @broccolini @ashygee

Bad styling on sidebar if the content is too short

👋

On Chrome and Firefox at least, if the main content is too short the styling of the sidebar on the left breaks

It can be tested with this URL for example https://primer.style/css/components/marketing-buttons

Search performance

Describe the bug
The search bar has a lag to it and does not show what I'm typing until I have finished typing.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://primer.style/css
2. Type (quickly) in search bar

Expected behavior
I expect the results to load quickly as I'm typing, such as on https://help.github.com/

Screenshots

Desktop (please complete the following information):

• OS: Mojave 10.14.5
• Browser: Chrome
• Version 74.0.3729.169 (Official Build) (64-bit)

Search performance

Serialize a pre-built lunr index 🎉

Support for table of contents (TOC)

Originally posted in primer/css#816 by @gladwearefriends

---

Bring back the bullet point outline list of links at the top of each guide

For example, on the old Colors guide

Glancing at this list lets me confirm if I am on the correct page or not (i.e. some topics as our border radius utility arent intuitive to me as to which page they live on - border? box?). The list also lets me jump to relevant section on the page quicker instead of scrolling.

Perhaps it was taken out for good reason but I just wanted to share my two cents!

SideNav Componentization Tracking Issue

This is a tracking/scoping issue for refactoring the SideNav component to be reusable.

Currently the SideNav component is hardcoded to work specifically for the blueprints project docs. I'd like to break it up into several different components to be added to the library. This will require a bit of refactoring to make all the components truly reusable.

Scope of Work

Separate SideNav into 7 components:

SideNav

• Container component that takes children and nests them in a Router with layout styling

Section

• Can take a path prop and children.
• Will only be rendered in the SideNav if the path prop matches the current url.
• Children's path will have the parent Section path appended to it's path.
• Children provided should ideally be SectionLinks
• Renders a NavList if no children are provided, by looking up children of the node the path points too.
• Feels a little too abstracted/magical/doing too many things 🤔 Might be better broken up into two different components? not sure because it is super helpful as is

RouteMatch

• Used to conditionally show/not show a chunk of content based on a path. For example, a chunk of Section components

NavList

• Renders a <SectionLink> for each child of the paths node. For instance - <NavList path='support'/> would render a <SectionLink> for each doc in the pages/support folder

NodeLink

• Takes href and children. If children aren't provided then it looks up the meta.title for the href and uses that for the title of the link.
• Not 100% sold this is necessary. Feels too magic.

SectionLink

• Same as NodeLink, but it renders bold when it's href matches the current path

NavLink

• Same as NodeLink, but it renders with black text when it's href matches the current path

Notes

• I like the functionality that these components provide, but I'm worried they're too tied to the file structure in next.js being perfect - feels sort of rails-esque. I'm currently considering if a different approach might make them more universal for anyone using React but not necessarily using Next.

• Naming could probably be cleaned up a bit. Especially between SectionLink, NodeLink, and NavLink. Do each of these components differentiate based on where they should be used, or how they change when the path matches their href?

Consider using Context for pages functionality

#7 (comment)

Responsive Header Navigation

Tracking issue for responsive header navigation

Search component:

• Moves to the far left of the header at smaller breakpoints
• Search results fill up width of screen
• Turns into icon only at smaller breakpoints

Top Nav:

• Is hidden in Header component at smaller breakpoints
• Displays above SideNav at smaller breakpoints
• Accordian dropdown for menu items

Render static versions of SVG animations server-side

@jhuashao made some really sweet animated versions of header images in (chronologically) primer/design#11, primer/react#413, and primer/css#692. We currently use next/dynamic to only render them client-side because the bodymovin package doesn't work server-side, but it would be nice to have the static SVG rendered server-side first so to prevent the flash of missing image (yes, FOMI) when it eventually renders client-side. Maybe an HOC like so?

import {createHeaderAnimation} from '@primer/blueprints/components'
import HeaderImage from './HeaderImage'
import animationData from './HeaderImageAnimation.json'

export default createHeaderAnimation(HeaderImage, data)

Another benefit of this is that we wouldn't have to add bodymovin as a local dependency for each of our sites, and could keep it up-to-date here. I think SVGR even allows us to override <svg> element attributes with props, so our component could add width="100%" height={null} to have it scale without us having to modify the SVG file after exporting?

Remove header link to `/team`

Following up the discussion in primer/primer.style#131 (comment), the header link to /team can be removed. A link to the team has been added in the index page (see primer/primer.style#131 (comment)).

/cc @emplums because primer/primer.style#131 (comment).

/cc @broccolini because primer/primer.style#123 (comment).

Add padding to CodeExample

Problem

Code examples that have outlines or box-shadows get cut of on the edges:

Possible solution

Instead of adding the "default padding" to the parent of the <iframe>, move the padding inside the <iframe>.

NavDropdown Component

In order to build the new Header, we'll need a NavDropdown component.

This component must:

• Use <details> element
• Open dropdown menu when clicked
• Close when anything outside of the menu is clicked
• If another Dropdown is clicked, that Dropdown should open and the previous one should close (maybe use Context for this?)
• Should be keyboard navigable
• When Dropdown is opened, focus should go to first element
• Should have correct aria labels

Bump up the contrast of the search input

Originally posted in primer/css#816 by @gladwearefriends

---

Bump up the contrast of the search input

When i looked for it the first time I glanced right over it and thought there wasnt an input. Adjusting the word Search to be lighter would be super helpful!

Header links run into vertical scrollbar

If/when a vertical scrollbar is visible in macOS, it runs over the last item in the header, as seen on primer.style/css:

We might want to just bump up the default right padding a notch.

New Components Tracking Issue

This issue is to track the remaining components that I'd like to add to Blueprints

Navigational Components #7

• SideNav
• Section
• RouteMatch
• NavList
• NodeLink
• SectionLink
• NavLink

Content Components

• StatusLabel
• Outline
• PackageHeader (added already, but needs documentation and further refactoring)

Need location for tools docs

Atom packages, docset, GH local environment, and linting don't map well to our new setup. In the new header, they are nested under a Tools section, but they live in primer.style/css. Should we have a Tools site that hosts the docs for all of these?