Mfon Eti-mfon (He/Him) (Jun 27 2022 at 13:51): Mfon Eti-mfon (He/Him) (Jun 27 2022 at 13:51):@Richard Feldman I've thought a little about how to tackle the work on the Docs UI, and I'm thinking to start by sending a PR that adds all the colors specified in the Figma document to the styles in docs/src/static (as CSS variables).
Is this a good way to start?
There'll be no visible changes with that PR, but I think it's a good idea because it makes all the color definitions available in one commit/PR.
What do you think?
Anton (Jun 27 2022 at 13:52):Sounds good, It'll be nice to have some agreed-upon color scheme.
Anton (Jun 27 2022 at 13:56):Perhaps we should make a style folder in the repo for this kind of stuff. A centralized place that could eventually become the roc style guide. With the logo, colors, fonts...
Richard Feldman (Jun 27 2022 at 13:57):sure, works for me! :thumbs_up:
Richard Feldman (Jun 27 2022 at 13:57):Perhaps we should make a style folder in the repo for this kind of stuff. A centralized place that could eventually become the roc style guide. With the logo, colors, fonts...
that will probably make sense in the future, although for now I'm fine with just getting the docs looking good :smiley:
Anton (Jun 27 2022 at 13:58):Yeah totally, for now the style guide could just be a md file with the colors.
Mfon Eti-mfon (He/Him) (Jun 27 2022 at 14:23):Awesome. I'll get to it!
Mfon Eti-mfon (He/Him) (Jul 03 2022 at 20:53):@Richard Feldman I think a good next step will be to contain headings and their associated paragraphs in a div so we can create the borders around them as per the design doc.
Screenshot-2022-07-03-at-21.50.55.png
What do you think?
Or are there any other CSS-only changes to be made?
Richard Feldman (Jul 03 2022 at 20:55):that makes sense to me! :thumbs_up:
Richard Feldman (Jul 03 2022 at 20:57):the html gets generated here: https://github.com/rtfeldman/roc/blob/04046cef39c9931a2951725e7724dca0caf62fd4/crates/docs/src/lib.rs#L193
Richard Feldman (Jul 03 2022 at 20:58):like for example here's where we make the <h3>: https://github.com/rtfeldman/roc/blob/04046cef39c9931a2951725e7724dca0caf62fd4/crates/docs/src/lib.rs#L222
Richard Feldman (Jul 03 2022 at 21:00):so you could probably do a buf.push_str("<section>"); right after DocEntry::DocDef(doc_def) => { and then buf.push_str("</section>"); before the end of that block
Richard Feldman (Jul 03 2022 at 21:00):to wrap the whole thing in a <section> (which I think semantically is what we want here)
Richard Feldman (Jul 03 2022 at 21:00):and then give that an outline in CSS
Mfon Eti-mfon (He/Him) (Jul 03 2022 at 21:28):Ah, thanks for this.
I was able to trace my way to render_module_documentation and was just trying to make sense of it :sweat_smile:.
Your message helps make it faster for me.
Richard Feldman (Jul 03 2022 at 21:34):glad I could help! Feel free to ping me with any other questions! :smiley:
Mfon Eti-mfon (He/Him) (Jul 03 2022 at 21:53):Somewhat related to this: what's the concept of a detached doc? In what ways do detached docs differ from doc defs?
I've just printed out a detached doc and it doesn't look like what I guessed it would be.
Mfon Eti-mfon (He/Him) (Jul 03 2022 at 23:00):I may have figured that out now.
Richard Feldman (Jul 03 2022 at 23:51):it's some documentation that's not attached to a particular type, and is just there for if you're reading through the whole docs from start to finish
Richard Feldman (Jul 03 2022 at 23:52):so it might be a section heading, followed by a brief introduction to the section
Mfon Eti-mfon (He/Him) (Jul 04 2022 at 01:52):So, I've worked on the spacing inside the <section>s -- (https://github.com/rtfeldman/roc/tree/mfonism/docs-ui/work-on-spaces-inside-module-entries). But I'm not really sure about the look and feel of it.
It looks alright when you're seeing one paragraph on top of the other. But when you throw <pre>s and codes into the mix, the spacing starts looking uneven -- or maybe it's just my eyes.
Screenshot-2022-07-04-at-02.44.16.png
Do the changes look good to you?
Richard Feldman (Jul 04 2022 at 04:09):
Richard Feldman (Jul 04 2022 at 04:10):yeah I agree, something looks off :thinking:
Richard Feldman (Jul 04 2022 at 04:10):but I'm not sure exactly what!
jan kili (Jul 04 2022 at 04:33):Maybe indent (left margin) the code snippets a bit?
jan kili (Jul 04 2022 at 04:35):Looking groovy by the way :)
jan kili (Jul 04 2022 at 04:36):Maybe also indent the entire section body (not header)
jan kili (Jul 04 2022 at 04:38):Is the fact that the vertical margins (of paragraph breaks, code snippets, and section headers) are overlapping making it visually hard to skim? Maybe decreasing vertical margin in places could help that
jan kili (Jul 04 2022 at 04:38):Feel free to ignore all those ideas haha
Brian Carroll (Jul 04 2022 at 06:45):I think what feels off at the moment is that the function signature has left padding inside its box, so the signature text ends up being further to the right than the body text.
Your eye is noticing the alignment of the text, not the boxes. Imagine removing the background colour from the function signature. I think part of your brain sees it like that, as just text with no styling.
Brian Carroll (Jul 04 2022 at 06:47):I would try putting the same left padding on the plain text as you have for the heading and the code snippets. I think that will look correct. All the text will be lined up.
Qqwy / Marten (Jul 04 2022 at 07:50)::thinking: Something you might also try, is how it looks when the spacing between a paragraph (<p>) and a code snippet (<pre>) is reduced (as the code snippet is usually an example of what was explained in the paragraph).
Last updated: Jul 05 2025 at 12:14 UTC