Comments (5)
Hey @pouretrebelle!
Love this issue and so happy to see this work happening.
Component page tabs
Some quick backstory - we are planning to update our component pages on primer.style.
-
The "default" (first) tab will include the code examples. Code is the default. Since we no longer need to include Rails in the docs, the default tab will be the PRC components. The name of the default tab is TBD, but it might just become overview.
-
The secondary tab would be guidelines, and this would include interface guidelines
-
Third tab would be Accessibility guidelines
I don't have a mock handy, but essentially:
Overview
(code examples, brief description) | Guidelines
(interface guidelines) | Accessibility
(a11y guidelines)
Component status table
Unfortunately, @dipree and I were thinking of removing the component status table, since we don't think folks are getting a ton of use out of this (or rather, the level of granularity is lost on folks. they just want to know if they can use the component or not).
We need to do more research, but the idea was to instead lean on highlighting the status on the individual component pages. Publicly, on the component pages, it should be Draft or Ready only. Internal states for quality tracking purposes is fine
Happy to chat anytime since there are a lot of moving pieces right now, but also curious if @dipree wants to chime in.
Was there a specific need to showcase the status table on primer.style/brand?
@dipree also wrote this up for more context: https://github.com/github/primer/issues/3317
from brand.
Speaking to Emily earlier this week we've agreed on the path forward - updating the tabs as suggested in her comment, and not pursuing a component status table, but possibly creating some internal reporting to raise visibility of component statuses. Technically this poses some issues though.
Current technical setup for tabbed view
- There is an MDX file each for the existing index (guidelines) and react tabs
- They each render a custom layout component which conditionally renders the status, table of contents, and includes a hard-coded tabbed nav (using current page location to determine the active tab)
- Title and description have to be duplicated in the frontmatter of each MDX file
The drawbacks of this are the content duplication, and having no flexibility of tabs - adding a third tab with this setup would be impossible without a lot more hard-coding and code+content duplication.
Proposed solution
Use a single MDX file for each component, using H1s to define tabs. A custom Gatsby plugin and custom layout component will turn the content into tabs within the page.
Advantages:
- No duplication of frontmatter
- Easy to define additional tabs as needed
- Leveraging Gatsby's in-built table of contents data to build tabs and ToCs
- No custom components in the MDX to make the layout changes possible, making this content more portable to whatever system we use next
- Remove the directory hierarchy between component pages with guidelines and those without (e.g.
Bento.mdx
andAvatar/index.mdx
, removing the two levels of directories will make it easier to scan components)
Cons:
- Each tab won't have its own url, but we can use hash links to link directly to tabs (since we'd be changing the
/react
path anyway this isn't a huge loss)- We'd want the hash links for H2s to still work as expected, so it'll be a bit of work to e.g. jump to the guidelines tab if you load at
#usage
- We'd want the hash links for H2s to still work as expected, so it'll be a bit of work to e.g. jump to the guidelines tab if you load at
- Need to write some custom Gatsby middleware to parse the page contents and wrap each section in a tab panel. I've done similar things before so it's definitely possible, but may be a bit messy
- Introducing H1s causes heading hierarchy headaches, because for good a11y each heading should be downgraded a level, but I don't want to mess with their appearance. I think for the MVP I'll leave it with multiple H1s and come back to this later.
I'm going to work on a spike to check the practicality of this solution, but I feel reasonably confident it's the right direction to go in given no viable alternatives. This is a fair bit of work for what would seem like a simple layout switch, but will leave us with a flexible system so a11y guidelines can be slotted in easily, and it could be a testbed for primer.style interface experiments/developments until we do away with Gatsby.
Thoughts/opinions welcome! @raytalks @emilybrick @dipree @rezrah
from brand.
@pouretrebelle thanks for this! I'd like us to invest time in working together with Primer Engineering to focus on Nextocat rather than making Gatsby work for this use case.
I'm in conversation with @joelhawksley to plan for this work.
In the mean time I'd recommend to focus on low hanging fruit within our Primer Brand documentation and Story book.
from brand.
@emilybrick I hear you're the person to chat about primer.style with! How do you feel about us copying your component status page for Primer Brand? I'm unsure whether it's worth trying to package up the components/styles you use for the status table or whether I can just copy them to this repo, I guess that depends on what your longterm plans are for docs infra. Perhaps we could have a call to check I'm going in the right direction with this docs work?
from brand.
Closing this out as we're not prioritising any significant Gatsby changes since Nextocat is ramping up in priority.
primer/doctocat#739 will be completed though as it's a layout bug rather than UX change.
from brand.
Related Issues (20)
- 🐛 [BUG] - `AnchorNav` focus is trapped on mobile HOT 1
- [Feature Request] Add support for passing additional data attributes to pagination links HOT 1
- [Feature Request] Add ability to attach analytics attributes to FAQ tab buttons HOT 1
- [Feature request] Extend the max-width of the Hero Component's H1 HOT 4
- [Feature request] Story scroll river HOT 3
- Links to Storybook from docs site don't work locally
- 🐛 [BUG] - Image aspectRatio prop is not applied to the Image component HOT 1
- 🐛 [BUG] - Advice: Animation impacting Contentful Paint performance for SEO Article page HOT 2
- Anchor links for `FAQ` Questions HOT 1
- [Suggestion] Expand link area of `SubdomainNavBar`
- 🐛 [BUG] - Misalignment of icons in FormControl.Validation HOT 1
- 🐛 [BUG] - Focus outline on fullWidth Select component doesn't fill entire width
- Improve Storybook quality - remove inconsistencies and add missing content HOT 4
- [Suggestion] Improve anchor link support on mobile in `SubdomainNavBar` HOT 3
- 🐛 [BUG] - Select component does not forward the name prop/attribute value
- Errors in CTABanner documentation
- [Feature request] Specs pricing table HOT 1
- [modification request] table styling in Prose HOT 3
- Update River interface guidelines to disallow button usage
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from brand.