10up/wp-component-library

A library of barebones front-end components built with WordPress and accessibility in mind.

10up Component Library

DEPRECATED. Please go to https://github.com/10up/component-library

A library of barebones front-end components built with WordPress and accessibility in mind.

Overview

At 10up, we strive to provide websites that yield a top-notch user experience. In order to improve both our efficiency and consistency, we need to standardize what we use and how we use it. Standardizing our approach to commonly-used front-end components allows us to understand better the inner workings of someone else’s project and produce better solutions for ourselves and our clients.

Each component in this library is built with simplicity and accessibility in mind, tailored to fit the often opinionated nature of WordPress core output. These components are intended to be easily adapted to any number of different projects and use cases.

All components are tested to be WCAG 2.1 Compliant.

Start browsing ☞

How to Use

To use a component, navigate to the component’s detail page to see demos, usage examples, and installation instructions.

Support Level

Active: 10up is actively working on this, and we expect to continue work for the foreseeable future including keeping tested up to the most recent version of WordPress. Bug reports, feature requests, questions, and pull requests are welcome.

Like what you see?

wp-component-library's Issues

Menu/dropdown - Documentation

We should document in the component itself that the markup is based on the markup generated by wp_nav_menu() and then provide a link to the Codex/Developer page.

Wrap static text in i18n functions

Since we're intentionally tying this so closely to WordPress, we should encourage best practices by wrapping all static text in i18n functions.

For example:

<span class="screen-reader-text">Primary Menu</span> 

would be better written

<span class="screen-reader-text"><?php esc_html_e( 'Primary Menu', 'textdomain' ); ?></span> 

Blogroll Component

@jonbellah and @timwright12, thoughts on having a blogroll component? It would include title, featured image, date, author and excerpt (with read more). This would eliminate https://10up.github.io/wp-component-library/component/readmore/index.html and have it as part of this blogroll component.

WCAG 2.0 Compliance for Logo Components

Per our slack conversation in #10up-frontend-team about WCAG standards in image ALT text being the only content within a link.

Primary Error:
Official word from WCAG 2.0 is that: “image alt text cannot be the primary text of a link"

Secondary Error (when using a heading):
"Heading tag found with no content. Text that is not intended as a heading should not be marked up with heading tags."

Reference: https://www.w3.org/TR/WCAG20/#perceivable

Small preview window shifts upwards

The "Open example in new window" button is floated right, so when the preview window shifts to the small size it no longer clears that float. Let's make sure that movement only happens horizontally when switching between preview sizes.

Link or button element for Primary Menu Trigger

Looks like we're using a link to trigger the off canvas open/closed. I've always been a fan of using button elements here since it triggers an action versus taking the user to a destination. Semantically, it makes sense here, but open to thoughts and suggestions?

          <a href="#menu" class="site-menu-toggle" aria-controls="primary-menu" aria-expanded="false">
            <span class="screen-reader-text">Primary Menu</span> ☰
          </a>

https://github.com/10up/wp-component-library/blob/gh-pages/_component/menu-off-canvas/component.html

References:
http://www.karlgroves.com/2013/05/14/links-are-not-buttons-neither-are-divs-and-spans/ http://rachievee.com/use-button-element-improve-accessibility/

Clarify local setup in README file

Just ran the commands to view the library locally and got a little stumped when it came time to view the site in the browser. The Github documentation tells you to go to http://localhost:4000 but that's not what worked for me.

Instead I just copied the server address into the browser that the command line provides once the server is running. Thought it'd be a good last step for the local setup area in the README to mention that as well as point to Jekyll documentation in case. Thoughts?

Other than that, setting up was so much easier than I expected. 😄

Question: Example.html or Component.html - tabbed or spaced indentation

I noticed in each component, we have an example.html file and a component.html file. The name example.html gave me the impression that this is the file being displayed for demo purposes, but it looks like the opposite is happening? Noticed the example.html files also follow spaced indentation. Just want to confirm what our expected workflow here is so I can ensure that I'm following it.

Thanks. 😃

Off Canvas Menu Hash

The '#hash' on the toggle link for the off canvas menu is set to #menu, it should be linked to the ID of the ul, which is #primary-menu

Introductory Text

Need to give the library a bit of history and context on the homepage. Creating an issue as a reminder to get this added soon.

Modal component API

Following our discussion on the call today, I'm just opening this issue as a reminder that we want to start following the same pattern that we're using with the navigation menu API with other components, where it makes sense.

The modal component is one where I see it being useful to have an API.

One option idea being whether you'd like the modal to open on load, exit intent, or some other arbitrary event.

Off Canvas Menu: doc is not defined

doc is not defined in .js

Local setup instructions: gem install bundle vs bundler

In the local setup instructions, should the commands be:
gem install bundler
then
bundle install

?

Need templated HTML for menu components

Accordion Functionality

For the accordion, it might be nice to use link hashes instead of buttons so we can get it functioning without JavaScript and the no-js UI would have dead buttons in it.

Tabs are broken without JavaScript

Content for the tabs doesn't display when JS is off. We could display all content for make the tabs work with :target (I'd like to see them work with :target for whomever fixes this)

Flexbox Grid

I think our default grid should be flexbox-based. I'm on the fence as to whether or not we should even provide a float-based option in the library. On the one hand, it'll likely be necessary for a fairly large number of projects just due to clients requiring IE9/10... on the other, flexbox support is sitting at almost 97% and will only continue to grow.

In either case, I would prefer that our grid avoid the use of presentational markup, and instead use mixins to include your grid; i.e., @include columns(6).

Would definitely like some thoughts and feedback around these ideas.

Navigation menu API

Wrap the menu javascript in a jQuery-style function, then expose a series of options to allow for basic customization (click-to-open vs hover, etc)

Tab .js: Doc is not defined

Easy fix, but doc is not defined in the .js of the tab component.

"Download JS" link

In the responsive nav component (and probably others), there should be a link to download the example code and another one for the library.

Remove Plugin Evaluation Spreadsheet

Remove all instances of the Plugin Evaluation Spreadsheet:
https://10up.github.io/wp-component-library/component/datepicker/index.html

Link out to accessible modal plugin

This is the first of a few tickets that I'll be opening that focuses on simplifying the JS that accompanies some of our components. We should link out to the accessible modal plugin the same way that we do for the Pikaday plugin.

Dropdown Menu Hash & ID

The #hash on the toggle link for the off canvas menu is set to #menu, it should be linked to the ID of the ul. The ul does not currently have an ID, it needs one.

iframe resize buttons

The addition of the 5th button under the iframe breaks on small screen: https://10up.github.io/component-library/component/breadcrumbs/ - this menu is meant to interact with the sizing of the iframe. It also alters the UX of the menu. The "new window" content should be linked to from the HTML heading like here: https://10up.github.io/component-library/component/accordion/ see "view generated HTML"

If we need something to pop the iframe out (what it looks like the new window button is doing), I'd recommend putting it somewhere else so that menu can be dedicated to resizing only and not get over crowded. Maybe text link above the iframe.

Hide resize buttons on mobile

Tab headers scroll awkwardly on small screens

Schema markup VS WordPress PHP markup

I'm seeing a lot of schema markup for SEO and wondering if there are components where it'd be more appropriate to lean towards what "typical" WordPress markup would look like as well, and then show how that can be combined w/ schema.

For example the "logo" pictured here:

https://10up.github.io/wp-component-library/component/logo/index.html

Can end up looking something like this in a theme (pulled from TwentySixteen):

<?php if ( is_front_page() && is_home() ) : ?>
    <h1 class="site-title"><a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home"><?php bloginfo( 'name' ); ?></a></h1>
<?php else : ?>
    <p class="site-title"><a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home"><?php bloginfo( 'name' ); ?></a></p>
<?php endif;

I've actually never used schema markup before so I'd love to learn what the best practices here are and how we can integrate it with WordPress markup. Thoughts and suggestions?

Schema markup VS WordPress PHP markup

I'm seeing a lot of schema markup for SEO and wondering if there are components where it'd be more appropriate to lean towards what "typical" WordPress markup would look like as well, and then show how that can be combined w/ schema.

For example the "logo" pictured here:

https://10up.github.io/wp-component-library/component/logo/index.html

Can end up looking something like this in a theme (pulled from TwentySixteen):

<?php if ( is_front_page() && is_home() ) : ?>
    <h1 class="site-title"><a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home"><?php bloginfo( 'name' ); ?></a></h1>
<?php else : ?>
    <p class="site-title"><a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home"><?php bloginfo( 'name' ); ?></a></p>
<?php endif;

I've actually never used schema markup before so I'd love to learn what the best practices here are and how we can integrate it with WordPress markup. Thoughts and suggestions?

Current Menu Dropdown loses :focus

The current menu dropdown component is no longer accessible via keyboard/on focus.

https://10up.github.io/wp-component-library/component/menu-dropdown/index.html

If you tab through the menu example via keyboard, you can focus into the menu without the menu actually expanding to see what you're focused on. Therefore I lose the focus indicator. With the menu open, I can do the same with the submenus, where the submenus do not expand, but I'm focused on those items without physically seeing that I am.

Also if we assume menus like this would be used for mobile, should we be triggering menus with on touch/click events versus on hover?

For suggested behaviors for the menu, I like to use W3 as a reference:

Menu Button
Menu or Menu Bar

Menu Components Readability

The nav links are hard to read in both menu components; how about some light styling or changing the black background to a lighter gray?

Implementation: Accordion - Selectors in styles are wrong

I was able to set up the accordion successfully, however I noticed something in the styles tripped me up a bit.

The styles for the accordion content use .js .accordion-content as a selector. However there isn't any JS currently in the accordion plugin to add or make use of a .js class. Works fine once I removed the .js class.

There's also a commented out line around line 95 that we might want to remove:

//content.setAttribute( 'tabindex', '-1' );

Basic Templating

Since we're targeting WordPress specifically, I think we should go one step further towards making this library dead-simple to use by handling basic templating; at least when it makes sense for 90%+ of use cases.

For example, with the author card, rather than listing Bill Murray as the author, we can just use <?php the_author(); ?> or <?php the_author_link(); ?>.

ARIA expanded does not revert to 'false' when accordion item is closed

As it stands, the accordion items retain aria-expanded="true" even after the user clicks the expanded accordion item to close it.

Provide PHP version of ReadMore's and other use cases?

Noticed our current Read More is a general approach for visually hiding text from screen readers. Wondering if we can include what some PHP (WP) read more's would look like as well?

Also thinking we could add some other use cases for the "read more" style as it's meant in general for other things as well like icon fonts or clarifying links that are otherwise not very clear on a screen reader. Not sure how far we want to go here - thoughts?

https://10up.github.io/wp-component-library/component/readmore/index.html

Menu component

Datepicker example opens outside iframe

Just documenting this. Know we're still refining everything.

Increase preview iframe height

Several of our examples have tall previews. Let's adjust the base iframe height to accommodate most of these cases (if there's an occasional scrollbar for super tall dropdown menus or something like that, I'm not going to sweat it).

Browser Support Tables

The browser support tables for items that were rolled back to use classList need to be updated to IE10+

Social Buttons / Links component

This is something I'm sure we use all the time, and while there's a lot of services that offer share buttons, most of the time projects want their own design or custom implementation, I think this could be useful.

I have these small code that helps me get most of the popular services, though I'd love to hear recommendations:

<section class="share-links">
    <!-- Facebook -->
    <a href="#"
        class="facebook"
            onclick="
                window.open(
                    'https://www.facebook.com/sharer/sharer.php?u=<?php the_permalink(); ?>&t=<?php echo urlencode( $post->post_title ); ?>',
                    'facebook-share-dialog',
                    'width=626,height=436');
                    return false; ">
        <svg xmlns="http://www.w3.org/2000/svg" width="100" height="100" viewBox="0 0 100 100"><path d="M71.31 50.034H57.368V100h-20.66V50.034H26.88V32.382h9.826V20.96C36.706 12.783 40.57 0 57.556 0L72.86.058v17.14H61.752c-1.81 0-4.384.908-4.384 4.805v10.38H73.12l-1.81 17.65z"/></svg>
        <?php esc_html_e( 'Facebook' ); ?>
    </a>

    <!-- Twitter -->
    <a href="#"
        class="twitter"
            onclick="
                window.open(
                    'https://twitter.com/share?text=<?php the_title(); ?>&url=<?php the_permalink(); ?>&via=CHANGEME',
                    'twitter-share-dialog',
                    'width=626,height=436');
                    return false; ">
            <svg xmlns="http://www.w3.org/2000/svg" width="100" height="100" viewBox="0 0 100 100"><path d="M89.223 32.76c.043.865.06 1.735.06 2.61 0 26.657-20.288 57.394-57.392 57.394-11.395 0-21.992-3.342-30.922-9.06 1.584.18 3.187.276 4.813.276 9.46 0 18.148-3.224 25.05-8.63-8.823-.167-16.276-6-18.838-14.012 1.23.234 2.49.366 3.792.366 1.842 0 3.625-.253 5.31-.712C11.878 59.14 4.917 50.986 4.917 41.214v-.255c2.724 1.51 5.833 2.42 9.14 2.522-5.414-3.616-8.973-9.79-8.973-16.787 0-3.697.996-7.162 2.73-10.142C17.758 28.76 32.63 36.788 49.39 37.628c-.342-1.476-.522-3.015-.522-4.597 0-11.14 9.032-20.168 20.175-20.168 5.798 0 11.043 2.45 14.722 6.367 4.59-.904 8.91-2.58 12.812-4.894-1.513 4.71-4.704 8.665-8.87 11.16 4.08-.487 7.97-1.57 11.582-3.175-2.7 4.044-6.12 7.597-10.063 10.44z"/></svg>
            <?php esc_html_e( 'Twitter' ); ?>
    </a>

    <!-- LinkedIn -->
    <a href="#"
        class="linkedin"
            onclick="
                window.open(
                    'https://www.linkedin.com/shareArticle?mini=true&url=<?php the_permalink(); ?>&title=<?php the_title(); ?>&source=CHANGEME',
                    'linkedin-share-dialog',
                    'width=850,height=436');
                    return false; ">
        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><path d="M56 41.7v-.2c0 .1-.1.1-.1.2h.1z"/><path d="M22.8 97.6H1.5V33.4h21.4v64.2zm-10.6-73H12C4.8 24.6.2 19.7.2 13.5.2 7.2 5 2.4 12.3 2.4s11.8 4.8 11.9 11.1c0 6.2-4.6 11.1-12 11.1zm87.6 73H78.5V63.2c0-8.6-3.1-14.5-10.8-14.5-5.9 0-9.4 4-11 7.8-.6 1.4-.7 3.3-.7 5.2v35.9H34.6s.3-58.2 0-64.2H56v9.1c2.8-4.4 7.9-10.6 19.2-10.6 14 0 24.6 9.2 24.6 28.9v36.8z"/></svg>
        <?php esc_html_e( 'LinkedIn' ); ?>
    </a>

    <?php $imgurl = wp_get_attachment_url( get_post_thumbnail_id( get_the_ID() ) ); ?>
    <!-- Pinterest -->
    <a href="#"
         class="pinterest"
            onclick="window.open(
                'http://www.pinterest.com/pin/create/bookmarklet/?url=<?php echo urlencode( esc_url( get_permalink( get_the_ID() ) ) ); ?>&media=<?php echo urlencode( esc_url( $imgurl )); ?>&is_video=false&description=<?php echo urlencode( esc_attr( get_the_excerpt() ) ); ?>',
                'pinterest-share-dialog',
                'width=850,height=600'
            ); return false;"
       >
        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><path d="M43.08 66.14C40.456 79.907 37.25 93.106 27.75 100c-2.932-20.808 4.307-36.435 7.668-53.026-5.73-9.646.69-29.062 12.777-24.277 14.873 5.885-12.88 35.865 5.75 39.61 19.453 3.91 27.395-33.75 15.332-46-17.428-17.683-50.733-.402-46.637 24.917.996 6.19 7.39 8.068 2.555 16.61-11.154-2.472-14.484-11.27-14.055-23 .69-19.196 17.25-32.638 33.86-34.497 21.006-2.352 40.72 7.71 43.443 27.47 3.067 22.304-9.48 46.46-31.942 44.722-6.088-.474-8.645-3.49-13.417-6.39z" /></svg>
        <?php esc_html_e( 'Pinterest'); ?>
    </a>

</section><!-- .share-links -->

.share-links {
  display: block;
  float: left;
  padding: 10px 0;
  width: 100%;

  a{
    color: #fff;
    float: left;
    margin-bottom: 5px;
    padding: 5px 15px 5px 35px;
    position: relative;
    &:not(:last-of-type){
      margin-right: 5px;
    }
  }

  svg{
    display: block;
    fill: currentcolor;
    height: 15px;
    position: absolute;
    top: 50%;
    left: 10px;
    transform: translateY(-50%);
    width: 15px;
  }

  .twitter {
    background-color: #2ca8d2;

    svg {
      margin-top: -1px; //negative margin to force these jerk svgs to look nice.
    }
  }

  .facebook {
    background-color: #305891;

    svg {
      margin-top: -1px; //negative margin to force these jerk svgs to look nice.
    }
  }

  .linkedin {
    background-color: #0077B5;

    svg {
      margin-top: -2px; //negative margin to force these jerk svgs to look nice.
    }
  }

  .gplus {
    background-color: #d34836;
  }

  .pinterest {
    background-color: #C82828;
    cursor: pointer;
    svg {
      margin-top: -2px; //negative margin to force these jerk svgs to look nice.
    }
  }
}

Modal dependancy files

Dependancyfiles (flexbox import & hash.click.js) are not being pulled into the library UI

Document JavaScript Browser Compat

We've discussed this, in general, being a 'last two versions' approach, but I think we should at least add inline documentation in places where we're using features that are not widely supported amongst older browsers.

For example, in the menu component, we use Elements.classList, which is IE10+. Totally fine for the vast majority of sites, but for those cases where IE8 or IE9+ is required, let's make it easy to spot those compat issues.

Center the large-sized iframe

When switching the large sized iframe, it expands out to the right only. Let's center it, especially since that's the pattern with the other sizes.

Setting aria-hidden to true on icons/symbols

Noticed we're dropping icons like the hamburger menu with this format (see screenshot). I know this is bare bones and we're not using an icon/svg font. Thought however we can use opportunities like this to show how to properly handle symbols like this accessibly by wrapping a <span> with aria-hidden="true" to prevent screen readers from trying to read them.

https://github.com/10up/wp-component-library/blob/gh-pages/_component/menu-off-canvas/component.html

Reference: https://css-tricks.com/html-for-icon-font-usage/

Tabs Not Working

Looks like there's a JS error preventing the tabs JS from rendering:

https://cl.ly/2w2M212g0L2D

Component placeholder images are still in the filesystem

component.png files are still sitting around in the file system

Mixing Tabs and Spaces

As much as it would pain me to go back into each file for this reason, the Best Practices says to use tabs: Engineering Best Practices and it looks like we're mixing tabs and spaces. Definitely not looking to get into a tabs vs. spaces debate, but it should certainly be uniform within the library. If we do go with the 10up best practices we may need some flags for linting as some will return "use spaces instead of tabs".

Indicate with ID/class names which elements are being targeted by JS

In our Best Practices, we call out:

In order to create more maintainable projects, developers should use classes for CSS and IDs for JavaScript. Separating concerns allows markup to be more flexible without risking breaking both styles and any JavaScript that may be attached to the element on which someone is working.

When using JavaScript to target specific elements in your markup, prefix the ID of the element that is being targeted with js-. This indicates the element is being targeted by JavaScript for your future self as well as other developers that may work on the project.

So, in this example, we should change id="datepicker" to id="js-datepicker" and update the JS accordingly, just to make it ab it more explicit where we're targeting things with JS so that people don't accidentally break things by changing ID's or something.

Table Component

Add a simple and fluid table component?

CSS rule ordering

Per the 10up Engineering Best Practices, rules within selectors should be ordered alphabetically. Minor, but important.

Dropdown menu click vs hover

In the dropdown component, a click on the hamburger toggles the menu open, while a hover over a parent menu item opens submenus. I wonder should these be consistent? Feels like Ben Grace and TD are always (often?) recommending click interactions.

Also, on mobile (at least in the chrome emulator) clicking a parent item to reveal a submenu causes the page to jump.

Sorry if I've missed any discussions about this last week while I was out.