InstUI: Instructure’s Style Guide 2.0

This blog from the Instructure Product Team is no longer considered current. While the resource still provides value to the product development timeline, it is available only as a historical reference.

aguthrie1
Instructure Alumni
Instructure Alumni
64
43095

Since its inception, Canvas has always been open and transparent about our business and our features. We believe in being open. We believe in allowing you to use Canvas the way you want to use Canvas. And branding is one component that we’ve been working hard to improve, specifically relating to the use of the existing style guide and Instructure UI (InstUI), Instructure’s own component library.

 

Branding Evolution

Web technologies continue to evolve, and over the last three years, we’ve been able to introduce the Theme Editor at the account level, which helps admins create custom templates without the use of custom CSS and JavaScript files, although those file types are still accepted.

 

Previously, Canvas engineers implemented a style guide to be used for internal engineering teams and ensure consistency throughout the product, hosted as part of each Canvas account (e.g. canvas.instructure.com/styleguide). Over time, we noticed that some of our customers started to leverage that style guide. We know that you enjoy being able to design your own Canvas-theme projects within the Rich Content Editor. Now, with the evolution of additional technology advancements, we’ve discontinued the use of the old style guide in favor of InstUI.

 

Why InstUI?

In order to use the styleguide, a developer or course designer would copy the HTML markup for a user interface pattern, such as tabs, and paste that markup throughout Canvas. However, HTML is only part that pattern. The style of those tabs is defined with CSS, and the interaction of navigating between tabs is enabled through Javascript. This architecture quickly became difficult to maintain. If we were to make a style enhancement or fix a Javascript bug that necessitated updating that HTML, every instance of those tabs—whether in Canvas, in a custom tool, or in course content—would have to be updated manually or remain broken.

 

To combat these maintenance challenges, we made the decision to move Canvas front-end development to React, a library developed by Facebook for creating modular user interfaces. React components encapsulate the HTML structure, the styles, and the Javascript together into a reusable, easily maintainable component. A bug fix to a React component propagates to every instance of that component with little to no effort, only needs to be made in one place, and every user immediately benefits.

 

InstUI, Instructure’s own UI component library, is built using React, which allows our developers to deliver new features more efficiently and makes all of Canvas easier to maintain and innovate. InstUI ensures consistent, accessible experiences throughout Canvas and delivers custom themes made with the Theme Editor to all interactions, just like the style guide intended. With React, those experiences are better tested, better maintained, and more reliable than ever for our users.

 

InstUI Availability

If you’re interested in using the InstUI components, InstUI is open source and available for you to use in your LTI tools. To get started, visit instructure.design. If you’re starting from scratch, InstUI works great with React boilerplates like Create React App.

 

We haven’t enabled the use of InstUI in the Rich Content Editor yet; however, other tools are currently available for integrating custom changes. Some options as noted in the community include H5P and other canvas embed tools.

 

Future Development

In 2019, the InstUI team will begin work to improve documentation and support for third parties.

 

Additionally, we recognize we don’t have an ideal solution for making changes in the Rich Content Editor. For now, we’re focusing on building a better Rich Content Editor to give you a better experience and give you more controls to design pages the way you want. This project is in the planning stages, and if you want to get more involved, watch for additional details to be posted in Canvas Studio.

 

If you’ve been using InstUI, let us know your thoughts in our InstUI Community Discussion.

 

If you’re not using InstUI but have used elements from the style guide in your pages, please let us know in the comments which elements you used and why they were helpful to you. Style guide feedback may be considered for future development.

This blog from the Instructure Product Team is no longer considered current. While the resource still provides value to the product development timeline, it is available only as a historical reference.

64 Comments
danielcktan
Community Contributor

hi  @DeletedUser ‌

Thanks for sharing the tip.

Yes I do have admin access to my Canvas instance and we have been making numerous changes to our instance by customising the CSS and Javascript of our Canvas theme.

Which files should we edit?

But you would have to make 2 small edits to a couple of files...or make a copy of them, and then edit them.

danielcktan
Community Contributor

hi  @DeletedUser ‌

Thanks for the clarifications.

The Tabs and Accordions require JQuery UI Tabs and Accordion widgets to be included in the theme's custom javascript to work. For your Dialog Solution, it work without the need to include JQuery UI Dialog widget to the theme's custom javascript. Hence I have the impression that your solution for the Modal Popup do not depend on JQuery UI.

As I have admin access to my Canvas Instance, I discovered that I can get Tabs, Accordions and Dialog to work on Canvas Mobile App when I include the code snippets for Tabs, Accordions and Dialog into the Custom CSS and Javascript for Mobile.

However, we need to tweak the CSS slightly for the rendering to be acceptable on Mobile App.

Modal Popup on Canvas Mobile App (iPad)

Accordion on Canvas Mobile App (iPad)

Tabs on Canvas Mobile App (iPad)

cheryl_colan
Community Contributor

The Bob Ross table is gold. Pure gold.

cheryl_colan
Community Contributor

I use the flexbox grid code too, so thank you for mentioning it!

cheryl_colan
Community Contributor

Yes! I can deal with Git on my own, but primarily use the RCE to help my faculty make their pages look nicer and organize content better. Using the styleguide to look up a CSS class that I can apply in HTML view is all I really need or want to do. 

cheryl_colan
Community Contributor

Robert Carroll wrote:

...

 

  • A robust, easy to use content editor, that allows everyone to paint happy clouds or at least happy little accidents, without having to know responsive web design or concepts like progressive enhancement and graceful degradation... or hiring someone who does
    ...
  • There should be a developer style guide, including buttons, modals, alerts, trays, sidebars?, etc – as well as a designer style guide, to access and utilize grid layouts, accessible tabs, and other interactive components that can be used, within the RCE and custom DOM through Theme Editor uploads.
    ...
  • and documentation to boot

 

I just want to pop in with a hearty AMEN to the 3 items above. I agree with most everything this post says, but these 3 are the most important to me. Thank you, Robert.

cheryl_colan
Community Contributor

These examples are beautiful! Thank you for sharing the screenshots.

cheryl_colan
Community Contributor

I just noticed this as well. I'm having to go back through my own past examples to find some of the code snippets. Disappointing.

cheryl_colan
Community Contributor

Deactivated user I wanted to chime in with a list of what I use from the Styleguide. My uses are entirely within the RCE in the HTML editor view, since I don't have access at my institution's Canvas instance level. My job as an instructional media developer involves helping our faculty organize and present information in a clear and visually pleasing way. So here's what I use:

  • styleguide#grid - the Canvas version of flexbox, especially the "be completely lazy" option to let the grid evenly distribute elements within the content box. I deeply love this for creating columns, particularly when content calls for a side-by-side comparison.
  • styleguide#buttons - in all the states (primary, secondary, success, warning, danger) and all the sizes (normal, large, small, mini) - because buttons help students know to follow a link more than just the standard hyperlink. I also combine these with icons - for example, a link to a file becomes a download the file button when I add the download icon
  • styleguide#colors - and background colors - whatever I can make work. I generally create a colored block like an alert to give emphasis to something on a content page that I really need students to pay attention to. 
  • styleguide#icons - especially the icon/text combo, icons added to buttons, heck, even displaying icons within instructions. If I want students to click a feature icon, why not show them what it looks like? Also the image/text combo - pretty sure I've used it or wanted to.
  • combinations - here is an example of combining styleguide items - in this case flexbox, alert, background color, and image/text combo and icon. These are literally at the top of every single activity or assignment or quiz that I assign to students in an online course so they can gauge how much time they need to spend - free feature idea for the RCE folks:
  • styleguide#tables - dear lord, this one truly makes Robert's Bob Ross table come into sharp relief. You have CSS for beautiful tables and all our faculty can produce using the RCE is an unstyled fixed-width table without even one pixel of cell padding / cell spacing. This is almost criminal for students who have to try to read tables in Canvas. I appreciate the caption styling too. Once in awhile I use the table row background color option to highlight important data, but I most frequently use the striped table with hover row"
    <table class="ic-Table ic-Table--hover-row ic-Table--striped">
  • Unstyled lists have occasionally been useful class="unstyled"
  • Description lists (referred to as definition lists in the style guide) - admittedly this is mainly just writing the HTML for the list - sure wish it were available via RCE - both normal and horizontal using 
    <dl class="dl-horizontal">
  • styleguide#color - sometimes sprinkled in for extra emphasis
  • styleguide#borders - with border radius - sometimes you just need to put something in a box - often combined with flexbox, alert, image/text combo, icon, colors - in courses for faculty we use this at the end of the content for citing sources in a pale gray box
  • content box, pad box and spacing - because sometimes the default rendering just doesn't work out well visually

I would deeply love a context-sensitive class selector button or dropdown in the RCE. For example the ability to choose the table class when editing a table, or the ability to choose a list style when editing a list, select a background color for a paragraph. It's the little things.

cheryl_colan
Community Contributor

no matter how many ways I tried to make this reply to Deactivated user‌ instead of Andy Davis, I always failed. Sorry.

James
Community Champion

There has been an update to the old StyleGuide.

I noticed today that the once-deprecated Styleguide received a bunch of updates a couple of months ago (committed in May, released in June 2020). I haven't seen any mention of it and it seems to belong on this thread, so I'm passing on what I discovered.

The StyleGuide is no longer labeled with a deprecated banner, it has been substantially reworked to remove irrelevant information, and does a good job explaining its purpose.

This page documents HTML and CSS components developed for use in Canvas prior to 2015. The code patterns documented here can be used to style content created in the Rich Content Editor (RCE). However, please note that these styles are no longer being actively maintained by Instructure.

If you're building an LTI tool with React.js, please use Instructure UI to visually integrate your app with Canvas.

When Arlo wrote that "everything you're doing right now will still work" in December 2018, I knew it was too ambitious of a statement. It is good to see that refined to things that will still actually work for now. Someone finally understood that InstUI 2.0 didn't serve the purpose that a lot of us were using it for and that the old StyleGuide needed updated to reflect the current status.

Covered are: Buttons, Borders, Forms, Grid, Icons, Spacing, Tables, and Typography.

Note that just because something is no longer in the StyleGuide doesn't mean that it doesn't work anymore. I wouldn't be as likely to use them as I would things that are listed, though. In particular, all of the interactive stuff is gone, but that is to be expected since these are things you can use in the RCE.

danielcktan
Community Contributor

Thanks  @James  for highlighting the updates! Smiley Happy

I am glad that the old StyleGuide has evolved to something end users can utilise for our instructional design while developers adopted the new React.JS.

Based on my observations, other UI elements like Tabs and Popup Dialogue Box still work.

For UI elements like Accordions, it requires some effort to make it work properly on Canvas. We adopted the solution shared by Deactivated user ‌to keep the accordions working on all our courses.

cgaudreau
Community Contributor

Sharing another resource for accordions, if time or knowledge to work with Javascript is a barrier to entry: The Disclosure Summary element - HTML: Hypertext Markup Language | MDN. It's not the prettiest, but works in a pinch if needed.

nagaed
Community Member

General question about the workflow to embed custom behaviour in a canvas page.

Hi, does anyone know about a general workflow to use Instructure's UI built on react into a self-hosted canvas instance?

I'm sorry if it's been dealt with in this thread or elsewhere but I can't understand or find any documentation about how one would embed some custom react code built on the Instructure UI into one's own Canvas instance.

Does the code need to be built and then embedded into a theme or should I be building an LTI?

Also, an unrelated question: does Canvas have a modular theme system like Wordpress (for e.g.)? 

From what I understand, some jQuery elements are phased out or removed in newer releases(?)

Finally, I have tried uploading custom Javascript via the Upload tab in the theme customization page (after enabling customizations) but have not been successful in getting it to work - even console.log() or windows.console.log() does not work. Is there another way to do this? I can write something to work with the custom js file without going through the React route but am unable to get past this issue.

Keen for some directions. thanks.