2023 Redesign CSS Updates

[KyraAssaad]

Sarven, I'm not a frontend developer. I am just trying to make improvements the way I know how, given the diversity of my background and experience. I am trying to get the styles correct from the design. I welcome your improvements to my improvements. But right now the way the CSS is structured, as a contributor I find it extremely difficult to parse and it is unlike any CSS I have interacted with before. So my work is going to be messy and not perfect, but it's going to get the site in a state where it accurately reflects the designs. Please feel free to make code suggestions that I can incorporate.

[csarven]

Kyra, I've pushed two commits that retains the HTML and re-applies your intended design changes (in this PR). Please have a look.

---

The current CSS may indeed be limited or "extremely difficult to parse" but that's mostly due to the accuracy of the HTML it is relying upon. As mentioned numerous times now, to get the HTML right (and the CSS thereafter), it needs to follow some clear documentation on the semantics/structure of the components on the site. There are obvious limitations to reverse-engineering a static visual design (i.e., 5 pages) into something coherent, and there is more to the site ( https://github.com/solid/solidproject.org/issues/842 ) that meets the eye. There are inconsistencies in the design itself, and that translates to inconsistencies in the HTML, and the mess that you are unfortunately dealing with in CSS. That's an issue for all of us.

Some concrete concerns were raised in https://github.com/solid/solidproject.org/pull/836#issue-2103520237 in addition to the initial design reviews. I hear your concerns and hope that you are also hearing mine.

[KyraAssaad]

Thank you @csarven, your HTML updates are helpful.

As mentioned numerous times now, to get the HTML right (and the CSS thereafter), it needs to follow some clear documentation on the semantics/structure of the components on the site. There are obvious limitations to reverse-engineering a static visual design (i.e., 5 pages) into something coherent, and there is more to the site ( https://github.com/solid/solidproject.org/issues/842 ) that meets the eye. There are inconsistencies in the design itself, and that translates to inconsistencies in the HTML, and the mess that you are unfortunately dealing with in CSS. That's an issue for all of us.

I hear your concerns and I agree with the comments raised. Let me see if I can address them:

It would be useful to have a style guide to ensure that the design is consistent, reproducible, and reusable.

@gisellewenban is working on producing this.

It is important to have a sitemap of all URLs under solidproject.org to ensure there is a record of everything, as well as the intended level of persistence for each resource. We will create an issue to track and introduce in later PRs.

I believe I can get a sitemap of all the current URLs, but I would appreciate your help on filling out the other details you mentioned, as you have more expertise in that domain than I do.

We did not have mobile designs, so we decided on layout that made sense.

@gisellewenban and I are working on these as well.

It would be useful to have a documentation of all components that are reused across the site's webpages, as well as structure (field/value) for each significant unit of information.

I believe we will be able to include documentation of the reused components in the style guide, but I'm not sure how to identify the structure, I'd appreciate your help on that as well.

cc @VirginiaBalseiro

[csarven]

I'll try to be brief about the (recurring / reusable) components here. Examples may serve best to classify certain things:

As I look at the content and the design, there is some notion about "feature" or "see also". I'd consider them as significant in and themselves. Their view/presentation (or even behaviour if need be) may be different slightly on some level but looking at it purely from the point of content/structure, they're are essentially the same. Some features/see alsos have very similar structure, links, images, etc for what they're intended for.

Typically the structure of articles and sections in these documents follow some hierarchy. Most of the pages that I've observed seem to have a single top-level heading (h1) for what the document (the article) is about. Everything else follows that. So, a design consideration is to signal information along these lines:

• which pages have a single h1? how are they designed (e.g., specify font or layout information)? which kinds of pages may have variations on those?
• how are the pages with multiple articles or (sub)sections are designed?
• what kind of recurring "aside"s are there across the pages?
• what kinds of item listings are there? how about definitions lists?
• what kind of short descriptions may be after a heading before subsections?
• what kind of pages are there (e.g., compare index, about, community, for-developers .. ) - put that into context with all the assets on the website: https://github.com/solid/solidproject.org/pull/856

(not an exhaustive list)

Even providing a default for those things helps to put the base structure and design in place. It is then really easy to spot errors or follow up on variations that are desired.

Another example regarding short descriptions on pages is something that confused me, and I think we all ran into trying to solve that in HTML and/or CSS without actually having a specific - explainable - answer for by looking at the visual design itself. For instance, compare the short descriptions (or subheadings or subtitles) for the following: index, about, for-organizations, community. It is unclear from the point of the structure where they sit. They can be part of a top level header but it could be very well different. For instance, when I was looking at the about page, I've initially included the two paragraphs (aside: doap:shortdesc) that follow the heading as part of the general description (aside: doap:description) of the about page. It was possible to style this just fine and still have the possibility for non-repeating machine-readable information. But then when we got into the PRs updating the styles, it became clear that perhaps that information should actually be outside of the general description. What I'm asking for here is not about how it should look but rather the intended structure of the document. Writing CSS is trivial if HTML is stable/flexible.

There are other examples but I don't want to hash them out. Perhaps one more: see how "Developer Tutorials" section and list looks in for-developers. Compare that to the section and list for "Available Solid Server implementations". The signal/information we need from all this is how or why are those things the same or different. Otherwise, everything just boils down to having something very custom and unique and can only be interpreted from the static visual information that's provided - which I find to be limited.

[michielbdejong]

Is this still incomplete?