Docs Site Audit - Scoping & Initial Styling#217
Conversation
noosheenv
left a comment
There was a problem hiding this comment.
Beautiful changes! I love the look of the callouts. I'm not sure if I did this right, but all the suggested changes are for one idea: keeping the links black, and turning pink on hover. In addition, the cards' borders will turn pink on hover. Here is a gif to demonstrate:
One more thing, I love the look of the "Key ValidMind Concepts" dropdown callout, but I would like the arrow to change state when it's clicked. For example, it looks like this
Everything is beautiful, thank you for doing such a thorough and complete audit!
This isn't actually possible without some JavaScript as far as I'm aware due to the nature of the call-outs, but I will see what I can do. |
|
EDIT: Also, this change was inspired by this comment from Nik: EDIT2: I think I still like the no-underline for links better, as this is what is seen in the training modules Nik has been creating as well, but accessibility... Nik, what do you think? |
nrichers
left a comment
There was a problem hiding this comment.
After playing around with this PR locally for a while my impression is very positive: this new look feels fresh and clean. 
All my comments are minor. I say we publish this as soon as you feel this is ready to merge.
Some general comments about styling:
- Pink AND bold for links feels off almost all of the time — we should not use bolding in links, except maybe to highlight some very specific things (e.g. it looks OK for notebook titles in a table, but anything inline or in a callout feels too heavy handed). I know we have a few of these kicking around, including some that I am responsible for. If the old link style was too plain and sometimes required bolding, I’d say the new one feels sufficiently strong that it does not benefit from bolding 99% of the time.
- Let’s be disciplined about minimising inline links, e.g. let’s not throw people off track with links to other docs in procedural steps or conceptual overviews. Much more visible links make this more important than before. The right answer should to put them into the links section at the bottom or to put things like glossary items into a newfangled flyout via Nutshell (the extension in my training PR).
- Our style guide will need more updates as reveal.js styling and HTML styling don’t overlap 100% and our training content will have some of its own requirements. I’m going to defer that to a separate story as I need to merge the training PR soon, but let’s chat more.
Also — the gift that keeps on giving — the links on the front page don’t behave like the links in the rest of the docs which is much more noticeable now. 😛
Obviously, I wasn't able to review the inconsistencies in any of the training modules @nrichers is working on. There are several instances of "Jupyter Hub" instead of JupyterHub for example.
I checked, there should be no misspellings of “JupyterHub”. Note the old "Welcome to the ValidMind sandbox!" topic is replaced by “Welcome to ValidMind Academy”.
EDIT2: I think I still like the no-underline for links better, as this is what is seen in the training modules Nik has been creating as well, but accessibility... Nik, what do you think?
I agree, no underline works better for me. Underline on hover looks good (could be black underline or pink, my preference would be for black underline on hover)
Noted, I will put this in an item in our next audit Story so I remember to catch any of these that are a bit much.
Looking forward to your Nutshell improvement, otherwise I already have an item for minimizing additional inline links (other than the login, you must login!!) one in the next audit Story.
Happy to defer to you there, or if you just tell me what you want those guidelines to be to be I can help. 🎉
Noted, and when I reviewed your branch this morning it all looked fine to me in this regard.
I ended up going with the black hover, and some shading on the cards on hover as well:
|
Internal Notes for Reviewers
New callout styling
Key ValidMind Conceptsto indicate an expand menu.callout-important)Links & content cards
Code content styling
I adjusted the style guide slightly to accommodate for our new code styling (with wrap / light grey BG that is a slightly different shade than our callouts) and cleaned up all the pages with code blocks:
Backticks
I added a
backtickssection to the Style Guide, and made sure we followed this convention on our pages.JupyterHub
I manually replaced all the files I was able to access on my branch and checked them to make sure they updated. Below is an example from the "Welcome to the ValidMind sandbox!" page.
Caveats