Anthony Bullard (Dec 11 2024 at 15:29): Anthony Bullard (Dec 11 2024 at 15:29):Screenshot 2024-12-11 at 9.28.06 AM.png
Something like this, but done in more than 1 minute in Chrome DevTools
It allows for navigating and to see the list of functions at a high level much easier.
Anthony Bullard (Dec 11 2024 at 15:30):With just a _hint_ of JS to also highlight the thing being viewed in the sidebar as well possibly?
Anthony Bullard (Dec 11 2024 at 15:31):Screenshot 2024-12-11 at 9.31.03 AM.png
Similar to Hex docs, which I have always found to be the gold standard
Anthony Bullard (Dec 11 2024 at 15:31):https://hexdocs.pm/elixir/structs.html#structs-are-bare-maps-underneath
Anthony Bullard (Dec 11 2024 at 15:33):A better example would be https://hexdocs.pm/elixir/Duration.html#from_iso8601!/1
Screenshot 2024-12-11 at 9.33.05 AM.png
Richard Feldman (Dec 11 2024 at 15:57):so the advantage would be that you can scroll the side bar without scrolling the main docs themselves?
Anthony Bullard (Dec 11 2024 at 16:47):Yes that, and you can look over and see the rest of the functions/types available at a higher level without scrolling the main content.
Anthony Bullard (Dec 11 2024 at 16:48):I understand search helps this a bit, but browsing is useful too, and browsing the main content takes a lot of scrolling
Richard Feldman (Dec 11 2024 at 23:16):hm, so my bias here is that having multiple scrollbars on the same page automatically creates a minor UX annoyance where you go to scroll and your cursor happens to be in the wrong pane and you have to move the cursor to do what you actually wanted to do. Whereas if there's only one scrollbar on the page, you can scroll from anywhere and it always does the same thing, so there's nothing to correct
Richard Feldman (Dec 11 2024 at 23:16):that said, an obvious downside of the single-scrollbar design is that you can't scroll one thing but not other; you can only scroll both at once :big_smile:
Richard Feldman (Dec 11 2024 at 23:17):so then the question becomes how valuable it is to be able to scroll one and not the other, compared to the inconvenience that it introduces sometimes where you have to move your mouse and redo what you were just doing
Richard Feldman (Dec 11 2024 at 23:17):and to be honest I'm not really seeing a significant benefit here :sweat_smile:
Richard Feldman (Dec 11 2024 at 23:18):today, if I want to see all of what's in the sidebar, then I scroll. The main content scrolls too but I don't really care because I wasn't looking at that content anyway, so it doesn't bother me that it's moving too
Anthony Bullard (Dec 11 2024 at 23:18):It’d be great to have more voices here
Richard Feldman (Dec 11 2024 at 23:19):(sure! I'll just finish my perspective real quick and then yeah)
Richard Feldman (Dec 11 2024 at 23:19):and the next thing I'm going to do is to click one of the sidebar entries anyway, at which point the main content is going to reset anyway
Anthony Bullard (Dec 11 2024 at 23:19):Since I don’t think I’m going to win an argument with the language creator when they admit they are biased against it :wink:
Richard Feldman (Dec 11 2024 at 23:19):well to be clear, I'm open to it
Anthony Bullard (Dec 11 2024 at 23:20):I’d like to - since I am a frontend guy first and foremost - create a prototype and share it
Richard Feldman (Dec 11 2024 at 23:20):there are plenty of cases where I start out having one perspective, and then after talking through it, I come around to another perspective :big_smile:
Anthony Bullard (Dec 11 2024 at 23:20):I know I was just joking
Anthony Bullard (Dec 11 2024 at 23:20):But would you like to see that prototype?
Richard Feldman (Dec 11 2024 at 23:22):the other scenario seems a bit more compelling to me, where I'm scrolling the main content and I don't want the sidebar to scroll because maybe I'm reading a long entry and when I'm done I want to click on the next thing...but then again, once I'm done reading the long entry, I can get to the next entry by scrolling slightly more anyway
Richard Feldman (Dec 11 2024 at 23:22):I think there's a separate design question about the screenshot at the start, which is where to align the sidebar
Richard Feldman (Dec 11 2024 at 23:23):today it's aligned immediately to the left of the main content, whereas in that screenshot it's aligned to the left of the browser
Richard Feldman (Dec 11 2024 at 23:23):so I think these are two separate questions:
Richard Feldman (Dec 11 2024 at 23:24):we've talked about the motivation for the scrolling, but I'm curious about the motivation for the alignment
Richard Feldman (Dec 11 2024 at 23:24):my default thought is that it means you have to move the cursor more to interact with it, which seems like a downside
Richard Feldman (Dec 11 2024 at 23:24):but maybe there's an upside I'm missing! :big_smile:
Richard Feldman (Dec 11 2024 at 23:25):also, of course you're welcome to make a prototype, but personally I've interacted with enough examples of these (and done a big pile of frontend dev myself :sweat_smile:) that I know how both designs feel already, so I don't personally feel I'd get a lot of signal out of actually trying it out but maybe others would benefit from it!
Anthony Bullard (Dec 11 2024 at 23:28):Believe me - I know your frontend creds, I'm a proud owner and read-to-completioner of Elm in Action - but I think this might come down to different styles of using docs. Especially as someone _learning_ the library by using and browsing. The design metaphor I'm talking about it more useful
For someone who knows the layout of the library fairly well and interested in some detail of an API they know already - I could see your perspective
Anthony Bullard (Dec 11 2024 at 23:28):So, in short, I think the scroll independently design is more Friendly (for beginners):smile:
Richard Feldman (Dec 11 2024 at 23:32):Anthony Bullard said:
I think this might come down to different styles of using docs. Especially as someone _learning_ the library by using and browsing, the design metaphor I'm talking about is more useful.
I think this is maybe the part I'm not following :thinking:
setting aside the metaphor, it seems to me that it's less effort to browse the overview in the single-scroll design, because:
bringing the metaphor into it, I guess it can help focus on the sidebar to see only that part scrolling and not the rest of the page scrolling in my peripheral vision?
Richard Feldman (Dec 11 2024 at 23:34):that said, when I've poked around Elixir's docs (not really using them in anger, just playing around with them to understand the design), I didn't even remember that the sidebar scrolled separately, so it obviously didn't make a big difference to me personally in practice :laughing:
Der Schutz (Dec 12 2024 at 00:27):I don't really have any hard opinions, but the single scroll bar seems rare and alien to me. There is a lot of UI's which have separate scroll-bars by default (i.e. browser PDF viewers, all the docs pages mentioned above, sidebar file trees, Wikipedia). I'm not sure if I can come up with a UI with a sidebar and main content where they are on the same scroll bar. I honestly have never ran into the inconvenience of scrolling on the wrong scroll bar. Personally I prefer 2 scrollbars, I don't like the part of the content scrolling when that is not the content I want to scroll through, also losing your spot would be annoying when you don't want to. But either way it isn't a big deal, but definitely different than what is common I'd say.
Sky Rose (Dec 12 2024 at 01:04):+1 that multiple scrollbars is probably easier to navigate even with the potential to scroll the wrong half.
Some other ideas to avoid having two separate scrollable areas:
Jasper Woudenberg (Dec 12 2024 at 07:31):I've found the builtins docs tricky to navigate, but for me it's primarily because the sidebar is long enough that it needs scrolling, rather than not being able to scroll it separately.
If I'm looking for a particular module's documentation I think the sidebar is tricky to use because the links for module's are so far apart, due to their exports being listed in between. Using Ctrl+F to find a certain module name is often hopeless given module names are often also type names and so appear in type annotations all over the main page.
If I'm looking for documentation for a specific function, like List.concat, I also have difficulty finding that in the sidebar. I can Ctrl+F to find the function name in the sidebar, but often I have to scroll up to see which module's documentation I'm in and see if I got the correct one. If it's not I have to go to the next search result, but because of the scrolling I've lost track of which search result I was looking at before.
Is it intentional design that the sidebar shows exposed functions across all modules? I think personally I'd prefer seeing only exposed modules there, because for navigating to the right function within a module I think the main text combined with Ctrl+F is good enough. But I'm curious if I'm missing a particular way of using the docs in which showing the full list of functions is handy.
Oskar Hahn (Dec 12 2024 at 08:14):I am not a fan of the current docs.
I am not sure what the best solution is. But would it be possible to try different solutions for a short amount of time? Like an experiment?
Anthony Bullard (Dec 12 2024 at 10:24):I can create a number of prototypes and share them out
Anthony Bullard (Dec 12 2024 at 10:25):Via GH pages
Anthony Bullard (Dec 12 2024 at 15:30):Here's prototype 1. The main page is NOT GOOD. I can fix that later. Gotta go to work :smile:
generated-docs.zip
It's just a zip of HTML. Use an http-server to view it
Anthony Bullard (Dec 12 2024 at 15:32):Screenshot 2024-12-12 at 9.32.02 AM.png
And a small preview for those that don't want to download a zip
Richard Feldman (Dec 12 2024 at 16:48):incidentally, I made some changes on a branch that hasn't landed yet, some of which are unrelated to this overall layout:
Screenshot 2024-12-12 at 11.46.31 AM.png
Richard Feldman (Dec 12 2024 at 16:49):specifically, removing the vertical purple lines in the sidebar and in the main content, and adding a purple box around the types in the main content
Richard Feldman (Dec 12 2024 at 16:49):I like the solid purple sidebar in that mockup!
Richard Feldman (Dec 12 2024 at 16:50):makes the body content look more distinct from it
Richard Feldman (Dec 12 2024 at 16:51):the only thing that's a little counterintuitive to me is that the search bar being styled just like the body content looks to me like it's dedicated to searching the body content, but it's actually searching both the body as well as the sidebar
Jasper Woudenberg (Dec 12 2024 at 18:28):So, based on that screenshot I realized most of the difficulty I described above are down to me using a browser with JS disabled most of the time, so please ignore :sweat_smile:.
Richard Feldman (Dec 12 2024 at 18:32):ahh interesting!
Richard Feldman (Dec 12 2024 at 18:32):well but that is a use case I care about
Richard Feldman (Dec 12 2024 at 18:33):so the reason everything is expanded in in the sidebar when JS is disabled is that you don't have the search bar available to filter them (which relies on JS)
Richard Feldman (Dec 12 2024 at 18:33):so I wanted to make sure everything is at least visible so that you can find it another way and click it
Richard Feldman (Dec 12 2024 at 18:34):the point about multiple modules exposing something named map and it not being obvious which if you're jumping around with the browser's search bar makes sense, but I'm not sure how we could improve it :thinking:
Richard Feldman (Dec 12 2024 at 18:35):like we could repeat the module name for everything, e.g. show the List module and then render it as List.map underneath (instead of map) when JS is disabled, but then a lot more entries will end up getting truncated due to running out of horizontal space, especially if they have a long module name
Anthony Bullard (Dec 12 2024 at 18:37):I made my prototype use JS-free view transitions so that when you click an item in the sidebar, the sidebar never reloads / loses state
Anthony Bullard (Dec 12 2024 at 18:38):And we can make some of the search work now without JS I think with the new select apis
Anthony Bullard (Dec 12 2024 at 18:39):Maybe search affordance could be better integrated with sidebar so it is obvious its package wide search
Jasper Woudenberg (Dec 12 2024 at 18:44):Richard Feldman said:
so I wanted to make sure everything is at least visible so that you can find it another way and click it
Another possibility is to keep the sidebar fully collapsed and instead show the full documentation for all modules in the main page body, with headers indicating the different modules.
The idea here being that I think the sidebar loses a lot of its usefulness if you can't see most of it without scrolling, but the main body text is long anyway, so if it becomes a bit longer that's no big deal.
Plus, the non-JS version could use anchor tags to jump to a specific module section in the main body, so you can jump around documentation without reloads same as in the JS version.
Jasper Woudenberg (Dec 12 2024 at 18:49):Separately, it might be an idea to add some module qualifiers in front of function names in hidden spans, then searching for something like List.concat should work. That could be nice, though only for people who know it's there.
Anthony Bullard (Dec 13 2024 at 00:18):I’ll make sure in my prototype that we don’t need JS for the jumping within a module
Anthony Bullard (Dec 13 2024 at 00:19):Unfortunately there is no way to highlight the current item being viewed in the sidebar without JS
Anthony Bullard (Dec 13 2024 at 00:20):And I think with datalist we might have a reasonable no-JS fallback for search
Richard Feldman (Dec 13 2024 at 01:13):interesting! I thought a datalist could only populate the value of an input, but maybe there's a way to turn that into a url change without js? :thinking:
Anton (Dec 13 2024 at 11:12):One random improvement I'd like to see is for the search bar to be fixed, so it doesn't disappear when scrolling. Search is extremely important for the docs experience, I want it available with minimal friction.
Anthony Bullard (Dec 13 2024 at 12:27):Richard Feldman said:
interesting! I thought a datalist could only populate the
valueof aninput, but maybe there's a way to turn that into a url change without js? :thinking:
Yeah, there was one leap I made that of course is wrong. I thought I could select on the chosen value and make a Go button (that's actually an a tag with the appropriate href value) appear. But I always forget that [value="Blah"] only matches the value attribute (default), and not the value property (current). So instead....,
The architecture would be to instead of a typing experience, it would instead take you to a "index" page of all the available modules and their members - each hyperlinked. You could then Cmd/Ctrl+F that page, get taken to the right link, and then hit enter on the focused link to be taken to the correct page. We'd probably want to pin the search affordance for this as well.
Anthony Bullard (Dec 15 2024 at 14:48):Finally had a chance to finish this prototype, addressing some feedback:
new-docs-template-desktop.mov
new-docs-template-mobile.mov
Anthony Bullard (Dec 15 2024 at 14:48):I'll push a PR as well
Anthony Bullard (Dec 15 2024 at 14:55):Here's the PR as a draft: https://github.com/roc-lang/roc/pull/7377
Richard Feldman (Dec 15 2024 at 15:04):love it!
Richard Feldman (Dec 15 2024 at 15:05):the desktop video made a strong case for two scrollbars, I'm sold on that :+1:
Richard Feldman (Dec 15 2024 at 23:51):btw the reason for the "duplicate" on mobile is that currently the main page for each package just says "Exposed Modules" and then lists them all again. It's kind of a placeholder until we get a doc comment header threaded through from the package's main.roc
Richard Feldman (Dec 15 2024 at 23:52):it used to be totally blank and looked broken on desktop
Richard Feldman (Dec 15 2024 at 23:52):but ideally it would be a readme-like overview of the package
Richard Feldman (Dec 15 2024 at 23:54):(except not in a separate readme file so that it can make use of things that are in scope, such as auto-links)
Richard Feldman (Dec 16 2024 at 00:01):also I'm not convinced we need the purple vertical bar and the indentation on the sidebar next to the things the module exposes. feels like just the indentation should be enough, and less eye-catching (which I think is desirable for the sidebar)
Jasper Woudenberg (Dec 16 2024 at 07:38):Cool demo, that looks really pretty and a nice improvement over the current site.
I'm still a bit concerned that when we're looking at the docs for a module with a lot of exports, the sidebar becomes bad for navigation to external modules (even in the JS-enabled world). My thinking is someone will turn to the sidebar either to find an export in the current module _or_ to find docs for another module, and whichever it is the information we show for the other use case is in the way.
One thought I had on the sidebar-scrollbar idea (for the desktop design, regardless of whether JS is turned on): What if the sidebar scrollbar would be limited to the uncollapsed list of module exports? So the sidebar would show all exported modules, then use the remaining vertical space to show a module's exports with a scrollbar, like a harmonica component. I guess this would only work if enough vertical space is available.
Another is to thought is to have some toggle to switch between module-listing and export-listing in the sidebar.
Yet another is to have separate sidebars for the module list and module exports, but that's a lot of sidebars and I don't know how well I like that option :sweat_smile:.
Anthony Bullard (Dec 16 2024 at 11:39):I think I could implement collapsing of the module exports in the sidebar without JS
Anthony Bullard (Dec 16 2024 at 11:40):Or sidebar for modules and minimap for exports on wide enough screens
Richard Feldman (Dec 16 2024 at 12:14):I don't think we need a minimap :big_smile:
Richard Feldman (Dec 16 2024 at 12:15):I'd like to keep the overall aesthetic minimal
Richard Feldman (Dec 16 2024 at 12:16):focusing on the content itself, trying to guide your eye to the hierarchy of where you're supposed to look first, second, third, etc.
Richard Feldman (Dec 16 2024 at 12:16):minimizing distractions
Anthony Bullard (Dec 16 2024 at 14:14):Yeah, personally I think for now, just getting rid of the border would be fine. Here are two options - remove it completely, and reduce to a thinne border with a more low-key color:
Screenshot 2024-12-16 at 8.13.06 AM.png
Screenshot 2024-12-16 at 8.13.41 AM.png
Anton (Dec 16 2024 at 14:57):We don't use lines that thin anywhere else, so it makes for a less consistent design. I would use a similar border width as elsewhere in the design and perhaps make it very low opacity.
Anthony Bullard (Dec 16 2024 at 15:06):Like this? 2px with .30 alpha?
Screenshot 2024-12-16 at 9.05.49 AM.png
Anthony Bullard (Dec 16 2024 at 15:06):In context
Screenshot 2024-12-16 at 9.06.43 AM.png
Anthony Bullard (Dec 16 2024 at 15:18):Here's another option for desktop - making the sidebar be a full third of the width (maybe capped at like 600px) - this helps avoid some clipping of members when there is a ton of unused horizontal space.
Screenshot 2024-12-16 at 9.17.16 AM.png
Anthony Bullard (Dec 16 2024 at 15:40):I also have fixed the scroll padding when clicking a link
Anton (Dec 16 2024 at 15:40):The "in context" version is good :)
Anthony Bullard (Dec 16 2024 at 15:40):Pushed my changes up to my PR. Feel free to play with it and give feedback
Anthony Bullard (Dec 16 2024 at 15:41):Do we create github pages for PR branches?
Anthony Bullard (Dec 16 2024 at 15:42):I'll check back at lunch. Gotta work
Anton (Dec 16 2024 at 15:44):Anthony Bullard said:
Do we create github pages for PR branches?
Not yet, we should set that up some time
Richard Feldman (Dec 16 2024 at 15:56):I like the low-opacity one! :+1:
Anton (Dec 16 2024 at 16:03):Pushed my changes up to my PR. Feel free to play with it and give feedback
I added some fixes to the www build script but I'm htting a segfault with the ssg md to html conversion so I can't take a look.
Anthony Bullard (Dec 16 2024 at 16:04)::grimacing:
Anthony Bullard (Dec 16 2024 at 16:04):Interesting not seeing that myself
Anton (Dec 16 2024 at 16:05):Feel free to play around with the two background colors of the sidebar and main docs, it feels like there is room for improvement there.
Anton (Dec 16 2024 at 16:06):Interesting not seeing that myself
Yeah, those can be device dependent
Anthony Bullard (Dec 16 2024 at 16:18):Yeah I thought of using a gray for the sidebar and using Roc violet as just a highlight color
Anthony Bullard (Dec 16 2024 at 16:18):Violet can be somewhat garish in large swaths
Anthony Bullard (Dec 16 2024 at 16:19):But I think Richard loves it :joy:
Anthony Bullard (Dec 16 2024 at 18:06):@Anton With grey sidebar
Screenshot 2024-12-16 at 12.06.17 PM.png
Richard Feldman (Dec 16 2024 at 18:18):the wide one definitely looks like too much purple to me haha
Richard Feldman (Dec 16 2024 at 18:30):Anthony Bullard said:
Do we create github pages for PR branches?
we deploy the site on Netlify and at some point we had that set up, but I think we changed it because it was using too many Netlify build minutes to have it on every PR
Richard Feldman (Dec 16 2024 at 18:30):at one point we had it only do that on builds to the www branch, but that was annoying in different ways so we stopped doing that
Anton (Dec 16 2024 at 18:35):We could probably limit it to running only if changes were made in the www folder or by requiring a message in the commit like [with-preview]
Anton (Dec 16 2024 at 18:42):Anton With grey sidebar
The drakness of the grey fits pretty well. Perhaps shifting the hue of that grey towards roc purple may make it even better.
Anthony Bullard (Dec 16 2024 at 18:43):Yeah, I could pull the hue out of it and lower the saturation and luminance
Anthony Bullard (Dec 16 2024 at 18:43):The new hsl(from ….) syntax is awesome
Anthony Bullard (Dec 16 2024 at 18:44):I can just go hsl(from var(—violet) h calc(s * 0.2) calc(l * 0.2))
Richard Feldman (Dec 16 2024 at 18:50):yeah I'm definitely open to color experimentation when it comes to the docs website. I don't want to change the main logo colors though (which are slightly different on light vs dark mode, of note)
Richard Feldman (Dec 16 2024 at 18:50):I've also tried to maintain WCAG AA contrast ratios
Anthony Bullard (Dec 16 2024 at 18:51):Yep. Always using those custom css properties and NOT touching them
Anthony Bullard (Dec 16 2024 at 18:51):And I’ll run A11y checks on my color scheme in light and dark mode
Richard Feldman (Dec 16 2024 at 18:51):sounds great, thanks for all the iteration on this! :smiley:
Anthony Bullard (Dec 16 2024 at 18:51):No worries
Anthony Bullard (Dec 16 2024 at 18:52):Great docs and great looking docs are often the front door to a language
Anton (Dec 16 2024 at 18:52):I can just go hsl(from var(—violet) h calc(s * 0.2) calc(l * 0.2))
By the way, I really like this approach on making color variants
Anthony Bullard (Dec 16 2024 at 18:53):That’s a nice resource
Anthony Bullard (Dec 16 2024 at 18:53):I’ll use the color science here
Anthony Bullard (Dec 16 2024 at 18:53):And be happy that CSS makes those tweaks easy
Anthony Bullard (Dec 16 2024 at 18:54):You don’t really need a separate tool anymore
Anthony Bullard (Dec 17 2024 at 22:42):Screenshot 2024-12-17 at 4.41.50 PM.png
Here's your "50 shades of violet" version @Anton :smile:
Luke Boswell (Dec 17 2024 at 22:43):Feels like a warm hug from my Auntie who loves to wear purple
Anthony Bullard (Dec 17 2024 at 22:43):And with the scroll bar
Screenshot 2024-12-17 at 4.43.03 PM.png
Luke Boswell (Dec 17 2024 at 22:44):Any chance you've got a light mode, for those of us who choose to live that life
Anthony Bullard (Dec 17 2024 at 22:44):I don't know or trust those people
Anthony Bullard (Dec 17 2024 at 22:44):j/k, of course
Anthony Bullard (Dec 17 2024 at 22:46):I'm glad you said something!
Anthony Bullard (Dec 17 2024 at 22:46):I have some work to do there :wink:
Anthony Bullard (Dec 17 2024 at 22:46):Let me find my sunglasses first
Luke Boswell (Dec 17 2024 at 22:46):If I sit in the office with "dark mode" enabled, people think I'm a hacker (doing evil things :smiling_devil:)
Anthony Bullard (Dec 17 2024 at 22:48):Screenshot 2024-12-17 at 4.47.39 PM.png
This is what is going on right now with it.....:sad:
Richard Feldman (Dec 17 2024 at 22:51):I want to be cool and pretend I don't think the 50 shades of violet looks rad but I cannot tell a lie...
Luke Boswell (Dec 17 2024 at 22:52):Anthony Bullard said:
Screenshot 2024-12-17 at 4.47.39 PM.png
This is what is going on right now with it.....:sad:
That purple sidebar is... a little too much
(edit) Also the white text in the type annotations is hard to read
Anthony Bullard (Dec 17 2024 at 22:55):Screenshot 2024-12-17 at 4.55.15 PM.png
:thinking:
Anthony Bullard (Dec 17 2024 at 22:56):Richard Feldman said:
I want to be cool and pretend I don't think the 50 shades of violet looks rad but I cannot tell a lie...
You just tell me the truth :-)
Anthony Bullard (Dec 17 2024 at 22:56):But I do have a bad eye for light-mode design anymore (I did in the past, but I still do, too)
Brendan Hansknecht (Dec 17 2024 at 22:58):Yeah, dark mode looks awesome colorwise
Anthony Bullard (Dec 17 2024 at 22:58):Screenshot 2024-12-17 at 4.58.50 PM.png
Luke Boswell (Dec 17 2024 at 23:04):I'm interested to know if @Georges Boris has an opinion too; he was pretty keen on design elements.
Anthony Bullard (Dec 17 2024 at 23:05):Screenshot 2024-12-17 at 5.05.16 PM.png
Added just a bit more detail around the search input in light mode
Richard Feldman (Dec 17 2024 at 23:05):Anthony Bullard said:
But I do have a bad eye for light-mode design anymore (I did in the past, but I still do, too)
RIP Mitch Hedberg
Anthony Bullard (Dec 17 2024 at 23:06):Richard Feldman said:
Anthony Bullard said:
But I do have a bad eye for light-mode design anymore (I did in the past, but I still do, too)
RIP Mitch Hedberg
I so love that you got this. Brings a tear to my eye. Much like this flashbang of a website I'm designing here
Anthony Bullard (Dec 17 2024 at 23:14):Looks like this is mostly ok, but there are some definite A11y issues with some of the colors (mostly the colors for the syntax highlighting). I wonder if it's the font size :thinking:
Anthony Bullard (Dec 17 2024 at 23:15):Doesn't seem to be
Anthony Bullard (Dec 18 2024 at 01:07):What would you think @Richard Feldman about us implementing a “high contrast theme” controlled by the prefers-contrast: more media query?
Anthony Bullard (Dec 18 2024 at 01:08):And then using that to serve our AAA experience?
Richard Feldman (Dec 18 2024 at 01:08):I've never tried that!
Anthony Bullard (Dec 18 2024 at 01:08):I just feel like AAA is going to look garish and brutal to people with normal sensitivity to contrast
Richard Feldman (Dec 18 2024 at 01:10):agreed
Richard Feldman (Dec 18 2024 at 01:10):we can get AA normally though right?
Anthony Bullard (Dec 18 2024 at 01:16):Probably. We need a few tweaks on some colors in light and I need to do an inventory on dark
Anthony Bullard (Dec 18 2024 at 01:16):I’ll put something up in the morning
Anthony Bullard (Dec 18 2024 at 01:18):Increasing the font size to 18pt/24px can also help
Anthony Bullard (Dec 18 2024 at 01:18):For AAA
Richard Feldman (Dec 18 2024 at 01:18):cool
Richard Feldman (Dec 18 2024 at 01:19):I'm not sure how many people actually use whatever settings trigger prefers-contrast: more
Richard Feldman (Dec 18 2024 at 01:21):huh, apparently a lot!
In terms of numbers, Microsoft states that 4% of Windows users use High Contrast mode. In the WebAIM low vision survey, 50% of low vision users indicate they used the mode but of course, that is likely a very self-selecting group of savvy users.
from https://polypane.app/blog/forced-colors-explained-a-practical-guide/#who-uses-this-feature
Richard Feldman (Dec 18 2024 at 01:22):both of these seem relevant to us, since 4% of Windows users is a lot of people in general, and 50% of tech-savvy WebAIM respondents is relevant to us because our users also self-select for being tech-savvy :big_smile:
Richard Feldman (Dec 18 2024 at 01:23):tweaking the colors seems better than bumping the font size because people can always use the browser zoom to bump font size (and may already have that bumped by default), and increasing contrast means the layout stays the same while making it more legible for those users
Anton (Dec 18 2024 at 10:47):Here's your "50 shades of violet" version @Anton :smile:
Those colors look perfect @Anthony Bullard!
Anton (Dec 18 2024 at 11:03):Some nitpicks:
Anthony Bullard (Dec 18 2024 at 11:18):Yeah, I'd like to minmax the sidebar to be clamp(min-content, max-content, 25dvw) or something like that
Anthony Bullard (Dec 18 2024 at 11:18):Right now I'm working on colors for mostly the code samples
Anthony Bullard (Dec 18 2024 at 11:18):And then I'll iterate on the entry headers
Anthony Bullard (Dec 18 2024 at 11:21):I think the content could be closer to the sidebar. but people like the whole "center the narrow content in the available space" design
Anton (Dec 18 2024 at 11:24):Yeah, the important stuff should be in the center
Anthony Bullard (Dec 18 2024 at 11:25):I just checked a bunch of languages, they either all do that, or they let the content be full bleed
Anthony Bullard (Dec 18 2024 at 11:26):Screenshot 2024-12-18 at 5.22.33 AM.png
Go likes full bleed code samples
Anthony Bullard (Dec 18 2024 at 11:26):But Gleam left aligns and narrows
Screenshot 2024-12-18 at 5.23.55 AM.png
Anton (Dec 18 2024 at 11:33):I don't like the go one, the gleam one seems pretty good.
Anton (Dec 18 2024 at 11:34):Sidebar on the right can also work:
scaladocs screenshot
Anton (Dec 18 2024 at 11:34):Anyway, not a priority to fix right now
Anthony Bullard (Dec 18 2024 at 14:03):Screenshot 2024-12-18 at 8.02.31 AM.png
Light and Dark (with AAA compliant colors throughout) side-by-side
Anton (Dec 18 2024 at 14:19):Nice :)
Anton (Dec 18 2024 at 14:21):One thing I'm wondering, are the subitems (like Utf8ByteProblem) in the sidebar the same fontsize as the text in the docs? They seem a little smaller
Anton (Dec 18 2024 at 14:22):The scrollbar color does seem exceptionally intense in light mode
Anthony Bullard (Dec 18 2024 at 14:24):Screenshot 2024-12-18 at 8.24.20 AM.png
WIth smaller sidebar
Anton (Dec 18 2024 at 14:25)::+1: I prefer the smaller sidebar
Anthony Bullard (Dec 18 2024 at 14:25):Sweet, looking at the module entries size now
Anthony Bullard (Dec 18 2024 at 14:25):And I'm unsure what to do about the scrollbar color. In both cases it is the "violet" color used for the logo
Anthony Bullard (Dec 18 2024 at 14:28):Screenshot 2024-12-18 at 8.28.35 AM.png
Larger sidebar entries
Anthony Bullard (Dec 18 2024 at 14:29):The module links are the same size as the body text, and the members are 2pt smaller
Anthony Bullard (Dec 18 2024 at 14:29):Otherwise it just looks garish
Anthony Bullard (Dec 18 2024 at 14:31):Screenshot 2024-12-18 at 8.31.23 AM.png
The same at 67% zoom (4 bumps down on Chrome)
Anthony Bullard (Dec 18 2024 at 14:32):Screenshot 2024-12-18 at 8.32.29 AM.png
And at 150% zoom (3 bumps on Chrome - last size before horizontal scrolling kicks in for main content)
Anthony Bullard (Dec 18 2024 at 14:33):I think these are really good looking docs that are highly accessible
Anthony Bullard (Dec 18 2024 at 14:34):And more functional than before
Anthony Bullard (Dec 18 2024 at 14:43):We'll have to get this on GH pages with proper compression and file handling to do lighthouse - locally it says light mode has a perf score of 72 and dark mode has a 94.
Anthony Bullard (Dec 18 2024 at 14:46):Perf report on mobile for light mode says 0.07s LCP, but Lighthouse says LCP for white mode is .24s. I'm done - pushing my changes and marking my PR as ready for review
Anthony Bullard (Dec 18 2024 at 14:47):Done
Anton (Dec 18 2024 at 14:47):Thank you very much @Anthony Bullard!
Anthony Bullard (Dec 18 2024 at 14:54):It's been my pleasure! I now will really enjoy using Roc Docs :-)
Anthony Bullard (Dec 18 2024 at 14:54):And I hope the rest of the community will too!
Anthony Bullard (Dec 19 2024 at 02:55):Don’t know why, but I can’t resolve this topic. Maybe someone else can?
Notification Bot (Dec 19 2024 at 02:57):Richard Feldman has marked this topic as resolved.
Last updated: Jun 16 2026 at 16:19 UTC