AngularJS Docs app - Materialized Mockup [v0.1]

[gkalpak]

This is my 1st attempt at creating "materialized" layout/UI for AngularJS's docs app (using Angular Material).

_{Note:
This is meant as a POC, so the implementation is not what it should be (e.g. no directives, everything in one controller for simplicity etc).
Bear with me, while this is still in progress 😃}

Resources:

• Screenshots
• Live-ish demo* (edit) _{(AngularJS: v1.3.4 | Angular Material: v0.6.0-rc3-master-98c3152)}

_{Current browser support: Works on **Chrome** **|** Works on **Firefox** (1-2 minor issues) **|** Almost works on **IE11** **|** Broken on **IE<11** *: Fun fact: Normally the demo preview has an annoying bar at the top that cripples the layout a bit. Opening the demo in a 2nd tab (i.e. opening it while it is already open in another tab), there is no bar !} ## #### Overview: - **Main content area:** Equivalent to the non-material version's main content area. - **Left sidenav:** Equivalent to the non-material version's left sidenav. It is "locked open" on larger screens and becomes a "normal" sidenav on smaler screens (brought up by a button in the top navbar). - **Right sidenav (search):** Contains the search-field and search results. It is "locked open" on large screens and becomes a "normal" sidenav on smaler screens (brought up by a fab (Floating Action Button)). - **Top navbar:** Contains the logo and the menu links/dropdowns (not implemented yet). ## #### "Highlights": - **Left sidenav:** - Adjusts to viewport size: - 20% / 25% / 33% on > 1200px / 960px / 600px respectively - hidden (+button) on < 600px - Section titles become "sticky" when scrolling. - **Right sidenav (search):** - Adjusts to viewport size: - locked-open on > 1200px - hidden (+fab) on < 1200px - **Logo:** - Adjusts to viewport size: - Full logo (large) on > 600px - Small logo (just the icon) on < 600px - **Color scheme**: - Attempts to make a visual reference to Angular's colors. ## #### Known issues: - The viewport size breakpoints need adjusting. - The colors need adjusting (e.g. a darker shade of gray might be more appropriate). - The right sidenav's backdrop does not cover the left sidenav. - The footer does not appear at the bottom, when the main content's height is less than the left sidenav's height. - Focusing the search-field (after clicking the search fab) is hacky and not reliable. - There is no animation, when showing/hiding/adjusting the sidenavs (as a result of viewport size changes). - On IE11: Some flexbox-specific properties do not seem to work (e.g. `align-items: center` (on `flex-direction: row`), `align-self: stretch`). - On IE<11: Broken (in many ways). _{**Note:** Most of the issues should be solvable. Some of them might be issues with Angular Material itself.} ## #### Todos: - Implement the version switcher. (Where ? What ? Ideas ?) - Implement the breadcrumb bar. - Implement the menu items dropdowns/submenus. - Support manually hiding/"locking open" the sidenavs. - Make the sections/subsections of the left sidenav collapsible. - Collapse the menu items on smaller viewport sizes. (Use BottomSheets instead of dropdowns on smaller sizes ?) - Test/Fix on more browsers (other than Chrome). - Test keyboard "navigability" / overall accessibility. - Add "material-design-ish" animations: - Top navbar: - Make the transition between large-logo / small logo more smooth (and "md-ish"). - Animate collapsing/expanding the menu items. - Left sidenav: - Make new view animate from point-of-click into the main content area. - Right sidenav (search): - Make new view animate from point-of-click into the main content area. - Animate the items entering/leaving the results list (as the user types into the search field). - Have the search fab morph into the search sidenav (and vice versa) the "Material Design way" ([example](https://www.google.com/design/spec/animation/meaningful-transitions.html#meaningful-transitions-visual-continuity)). - Search enhancements (e.g. as described [here](https://www.google.com/design/spec/patterns/search.html)): - Enabling voice search. - Providing historical search suggestions based on recent user queries. - Offering auto-completed search suggestions that match actual results in your application data ? _{Wondering: Would it be more appropriate to place the logo on left sidenav (when locked open); similar to how it's currently done on [material.angularjs.org](https://material.angularjs.org) ?}

[petebacondarwin]

Nice work @gkalpak!

I like the search fab on the righthand side when search is collapsed. That search panel should not be locked open at any resolution IMO.

I am not keen on the colour scheme yet. Looks a bit sad.

Can we make the sections in the nav collapsible?

Make new view animate from point-of-click into the main content area.

This would be nice!

The navbar font looks a bit big to me. Is this standard? Perhaps it is just the color scheme?

I would put the version picker inside some menu, perhaps as a collapsible item in the left sidebar?
Perhaps with a fab?

Generally I think this is a good start and you should move forward implementing it @gkalpak, since I think it is definitely moving in the right direction.

@caitp, @jesselpalmer and @joshkurz - any comments?

[joshkurz]

@petebacondarwin I agree. this is a great step in the right direction. we can make all of these other changes as we go, but I vote we merge this in and start working on other things with this as our base.

[jesselpalmer]

Thanks for putting this together @gkalpak! Using this as a base as @joshkurz suggested should save us a lot of time and we can just iterate on top of that.

[petebacondarwin]

I think this is only a mock up. @gkalpak was going to implement it "for real" if we didn't hate it.

[joshkurz]

well I like it. There is so much todo, I just wanted to make sure we were not trying accomplish all of it before we merge. I thinks its ok even with fake info in it for now. We can keep iterating on it. Better than one huge PR or commit for the base.

This contains allot of great work, I don't think we need to keep massaging it, before we actually use it. We can just use it and then make it better as we go. I say send a PR of this and lets talk about anything high level we want to change. Architecture wise and things, but implementation wise I think what this offers is fine.

[gkalpak]

Thx for the feedback, guys.

In the Todos section, I have listed the things I believe we should (or would be nice to) have (eventually). I didn't mean that as a precondition for merging this in.

It needs a little more thought for actually incorporating into the Docs app (e.g. what parts should be directives, what controllers are needed etc). I will try to get it in on Thursday (my GMT+2 Thursday) (this week is a little "heavy" job-wise).

---

Regarding pete's comments:

[...] That search panel should not be locked open at any resolution IMO.

Docking it wasn't my original intention either, but as I was thinking more about the app and trying to figure out what the main action would be (I badly wanted to use a fab, I admit it) and how we could improve usability (especially on mobile) it occurred me that the app could be more "search-centric" (for a couple of reasons):

1. It's the main purpose of the app: People come to find information (we should make it super-easy for them).
2. There is a fair amount of work put into making the app searchable (lunr + worker threads etc) that adds real value to the app, and the UI should make that value available to the user in the easiest way possible.
3. Between us, there is a lot of great content in those docs, but locating it is often a puzzle (for the majority of the users that are not familiar with the source code). (My favorite: "Looking for documentation on directives ? You should go to $compiler !?") Organizing the content more intuitively and at the same time keeping the docs close to the source code is not an easy task, will add complexity at some layer and is not very likely to happen soon (if at all). Making that content easily accessible through searching (instead of using the navigation sidenav) ? Super easy :)
4. Judging from myself, regular users tend to visit few specific pages on the docs most of the time. Having to scroll all the way down to the ngResource module to refresh my memory about the order of $resource arguments hurts the UX. Having a search-field with auto-complete and suggestions based on most recent/frequent queries would make me happier :)
5. It's a Google project (duh !).

So, I envisioned a new Docs app, where searching will be the primary way of navigating through the app (well...that and scrolling, of course :P). An app that puts every available resource on my fingertips. An app that knows what I need before I do myself. An app that makes it so easy to use Angular, as if it were my own code. From the first moment !
Yeah, whatever, dude !

Just kidding, but my thoughts were along those lines ((1) - (4); (5) I just made up now).
_{(And just because I wrote a long comment, it doesn't mean I feel too strongly about it - I really don't.)}

I am not keen on the colour scheme yet. Looks a bit sad.

😄 These are not my colors of choice either, but used them anyway for 3 reasons:

1. According to those Google I/O videos, it is a good idea to base your app's colors on your logo (and unfortunately Angular's logo isn't the most cheerful around :P).
2. According to the same videos, you should have more mundane colors on "boring" sections like settings etc. And I thought, "Well the whole app is about documentation; it can't really get much more boring than that :)", so I refrained from making it more playful (and very successfully so, since you find it sad 😄).
3. I am not a designer :P
   But I have it on the todo list to change the colors, so... :)

Can we make the sections in the nav collapsible?

Good point - will update the todos.

The navbar font looks a bit big to me. Is this standard? Perhaps it is just the color scheme?

It is the md-toolbar { ... font-size: 1.3em; } style, so I guess it is "standard". (Although I don't think there is anything "standard" about Material Design atm.)

I would put the version picker inside some menu, perhaps as a collapsible item in the left sidebar?
Perhaps with a fab?

I don't think fab is a good idea:

• "Try to use only one floating action button per screen, as it should represent only the most common action and is prominent on the screen."
• "Don’t attach a floating action button to a side drawer; it could distract a user from the task they want to accomplish. Side drawers are for navigation."

I guess a "dropdown"-ish item at the top of the left sidenav would be OK. What bothers me a little is that I would prefer to have the version more prominently visible (e.g. when the sidenav in closed on smaller screens).

[amoch-gannett]

@gkalpak

@jesselpalmer asked me to review some of the designs. Here are my suggestions:

3 columns vs 2 columns

I would stick with a floating header with two columns underneath it similar to the documentation that AngularJS already has

https://docs.angularjs.org/guide

It's clean and simple. People want large content areas and by making it 3 columns you're removing a portion of that view space. If users need to search for something they will want to see the results listed in large, clear results not confined to a small column. The existing AngularJS documentation does this rather well.

If I understand the mockups correctly it looks like the right column will slide out? If so, I still feel that this interaction is not completely desirable.

As far as having multiple elements floating along the page, I think that it's fine to do so. you will ultimately have a header and a left column floating along with the view and this is fine. I do agree that having a floating drawer toggle is not really necessary, and would probably get in the way (hence the 2 column VS 3 column design)

You might also consider using a library like slimScroll (http://rocha.la/jQuery-slimScroll) to pull the scroll bars away from the browser and get even more space and a cleaner look.

hope this is helpful, if you have any other items you'd like some extra eyes on I'd be happy to help.

[gkalpak]

Thx for the review @amoch-gannett.

This is a very early prototype; we are still exploring Material Design (conventions, components etc).
I guess much will change along the way.

So, feedback is very welcome and your suggestions have been noted 😉

BTW, I was thinking about "docking" the right sidenav on larger screens (I mean really larger).
Right now I use a preset (set at 1200px) which is still not wide enough to justify restricting the main content area.
But, at say 1500px, do you think it would be OK to have the search pane docked ?

[petebacondarwin]

I think the official term is 'pinned' rather than docked, which for me sounds like "attached to the side" as opposed to a "floating" window.