primer.style content audit & reorg

[emilybrick]

This issue is to take a look at the current way we're organizing content across primer.style and restructure as we see fit. There are redundant pages across primer.style sites, pages that no longer belong where they currently are, and confusing or misleading titles.

Let's see if we can clean this up and provide a more useful foundation for these pages moving forward.

[emilybrick]

Current structure:

Primer.style

Interface Guidelines

• foundation
  • color
  • typography
• global
  • accessibility
• UI patterns
  • button usage
  • progressive disclosure
• design tools
  • figma
  • sketch

Octicons

Prototyping

Primer CSS

• getting started
• tools
  • atom packages
  • docset
  • linting
  • local dev
  • prototyping
  • sketch templates
  • testing resources
• principles
  • accessibility
  • HTML
  • SCSS
• support
  • breakpoints
  • color system
  • marketing support
  • spacing
  • typography
• utilities
  • *all the things
• objects
  • grid
  • layout
  • table object
• components
  • *all the things

Primer Components

• system props
• primer theme
• components
  • all the things

News

Team

Proposed Structure

Primer.style

Guidelines

• foundation
  • color
  • typography
• principles
  • responsive
  • accessibility
  • SCSS
  • HTML
• UI patterns
  • button usage
  • progressive disclosure

Octicons

Resources

• atom packages
• docset
• linting
• local dev
• prototyping
• testing resources
• design tools
  • figma
  • sketch (do we still need this?)

Primer CSS

• getting started
  • contributing
• support
  • breakpoints
  • color system
  • marketing support
  • spacing
  • typography
• utilities
  • all the things
• objects
  • grid
  • layout
  • table object
• components
  • all the things

Primer Components

• system props
• primer theme
• components
  • all the things

Team

News

[emilybrick]

What changed

My proposal here is to change the following things:

• Change "interface guidelines" to just "guidelines", which include principles (accessibility, responsive, accessibility, SCSS, HTML). I still think principles might be the wrong word here to describe what this grouping is.

• Include a resources page at the top level of primer.style (instead of prototyping - name TBD), which includes the tools section from the former primer.css. Could definitely be missing important context here, but I'm not sure why prototyping needs to be at the top level. I think if I were to look for prototyping documentation (if it weren't at the top level), I'd navigate to something like tools/resources

☝️ caveat: this doesn't need to be it's own page. It could live within guidelines, for example. I just don't think it makes sense tied specifically to Primer css (as it is currently)

• Move the design tools page out of guidelines and into resources (or into a section in guidelines) . Happy to discuss, I'm not sure what value they're providing if not resources

cc @emplums @ashygee @broccolini

[emilybrick]

Here's the structure if we included 'resources' on the Guidelines page

Proposed Structure

Primer.style

Guidelines

• design foundation
  • color
  • typography
• development principles
  • responsive
  • accessibility
  • SCSS
  • HTML
• UI patterns
  • button usage
  • progressive disclosure
• tools
  • atom packages
  • docset
  • linting
  • local dev
  • prototyping
  • testing resources
  • design tools
    • figma

Octicons

Primer CSS

• getting started
  • contributing
• support
  • breakpoints
  • color system
  • marketing support
  • spacing
  • typography
• utilities
  • all the things
• objects
  • grid
  • layout
  • table object
• components
  • all the things

Primer Components

• system props
• primer theme
• components
  • all the things

Team

News

[ashygee]

@emilybrick I think this is a good proposal!

I'm curious about why we separate foundation from principles. From my understanding they can be one and the same. Would it make more sense to separate by function e.g. design and development?

• Resources (Tools?)
  Similar to above, I think maybe we can put these into more dev and design categories. I know for prototyping @broccolini and I have spoken about putting this under a Design Tooling category.

* sketch (do we still need this?)

I don't think we need to include this anymore. By now we've moved everything to Figma.

Other than that I think this is great 😄

[emplums]

This looks good to me! I agree that Principles vs Foundation is a little tricky 🤔 but don't want to bike shed to much! I think this is a great start :)

[simurai]

Is the plan to have just one big navigation for everything and remove the top header navigation (currently What’s New | Design | Development | Team)? If so, here some more ideas, that maybe are a bit out of scope 😇 .

• Collapse 1st or 2nd level of the nav. So that you don't always have to scroll down to get to the (I assume) more commonly used utilities and components.
• Make the nav vertically scrollable (independent from the body) and not reload, but replace the page (AJAX). So that you don't lose the scroll position when navigating between pages.

Here an example of the Gatsby docs.

[emilybrick]

Is the plan to have just one big navigation for everything and remove the top header navigation (currently What’s New | Design | Development | Team)?

No, I wasn't planning on changing the top level navigation. Just what lives within each Primer site (and Primer site nomenclature)

That's an interesting idea though, re: Gatsby – would be down to explore that.

[emilybrick]

After chatting with folks last week, we decided to take another look at the primer.style IA and organize as we saw fit. This screenshot of the sitemap includes sites and content we don't yet have (such as illustrations guidelines), but is a good picture of where we want to go:

Next steps:

• Move this content into a google sheet to get a clearer picture of what's missing and what needs to be moved
• Meet with Site team to discuss/go over

[ashygee]

IA sync notes

Want to organize primer and brand guide by audience. Primer for staff to use to create GH. brand guide if external partner and need marketing collateral to talk about/represent GH, know the correct logos, etc.

Right now very overlapping. Want staff to come to one place. Goal: Teams together are using all sorts of parts of primer. And easier to find. We want people to feel like GitHub's design system. Not just design system's design system. Work to improve the way we build and let others build and own docs in the future.

Overview on Primer.style and feedback from site time on docs

• how using changes, etc.

Currently broken into design, dev, and about/team
Future adding

• tools (figma, prototyping)
• content

Design

• Iconography include Octicons/GitHub Icons.

  • Probably don't want code to live in same place
  • Maybe both Octicons and GH Icons can live in same place.
  • We want docs to live with code/assets

• Interface guidelines

  • Include brand as a spectrum
    • https://brand.github.com/intro/spectrum
  • Could have separate marketing section
  • Marketing site guidelines added and defined
    • What is in primer is documented
    • Possibly more that isn't in primer but we can add more

• Add skullface's email template issue

  • Immediate: have docs findable
  • long term have code set up better
  • Future: move docs and code into same place

• Social Card

  • Cat wrote up docs
  • Files in Figma
  • Site team talking with engineering for code to add meta data.
  • Could be a component. Put into guidelines for now?

• Current site is very bare bones, want to build out

• What would it look like if we had...

  • illustration guidelines
  • Tools
  • imagery

Development

• CSS
  • Revisit how we group packages and marketing styles
  • Think about hierarchy of nav
• components
• blueprints

Had dev principles in design but not sure where to fit.

• we have that are generalist (responsive), put it in design & crosslink
• we have that are specific to language. put it in specific areas.

What we need to work on

• Make search better.
• Have more overarching site design docs
  • Design: Interface guidlines > site visual style
  • Dev: Primer CSS
• Combine marketing/site team figma files to be more cohesive

[ashygee]

I'm curious about what we might be including with imagery. Something I was thinking about is whether or not we would include avatars into that category or if this would still be under components. I know there has a lot of re-defining within how avatars have been represented.

[simurai]

@ashygee and need marketing collateral to talk about/represent GH, know the correct logos

Does this mean moving https://github.com/logos to https://primer.style? I think that would make sense. Although a concern might be that primer.style feels less official? And not sure if there is a legal concern too? 🤔

Want staff to come to one place.

💯 That would be awesome. Would also be nice if the "Web System" documentation would be included. Because when authoring github.com's markup, you probably want to add CSS styling AND JS behaviour at the same time. Maybe we can call it "Primer JS"? 😬😇

[broccolini]

Some quick notes to clarify things:

• We want to improve findability and have staff be able to find docs easily, hopefully completing tasks with docs in one place. That does not mean moving all docs ever under Primer, just docs that are directed at the staff audience when building interfaces and other collateral for GitHub.
• Web Systems are building their own docs site which they want to build in Jekyll. Since it’s completely separate JS rather than UI components like our React component library which contain all the presentational code together, I think it’s fine to host that wherever the team prefers. We’ll cross-reference that site where it makes sense to.
• We won’t move logos under Primer, Primer docs are for staff building GitHub, brand and logo guidelines are for people to use when talking about GitHub
• Blueprints should not be in the Primer.style nav because no one will use that to build GitHub websites. Blueprints are for building Primer docs sits only. We should link to this under contributing guidelines.