Call for design input
Locked
 
Administrator
|
In addition to the ongoing discussion about the project logo (https://github.com/asciidoctor/asciidoctor/issues/48), Asciidoctor could greatly benefit from the participation of designers and designer-oriented folks in other areas as well.
I'll start by saying that one of the goals we have for Asciidoctor is to make documentation beautiful. We've made some progress on this front by bundling a reasonable default stylesheet and by accommodating custom styles (see the gallery at https://github.com/asciidoctor/asciidoctor.org/issues/270 and HubPress.io). But we're no Medium yet. In other words, there's still plenty of progress that can be made. The first area of focus is the typography and colors in the default stylesheet. I think they could be much better than they are. All the styles are shown one way or another in the Asciidoctor User Manual (http://asciidoctor.org/docs/user-manual/). There are some specific items that I think need attention more than others: * A consistent color palette that is applied to headings, links, inline literals, etc (I really tried, but it's the best I can do) * Colors and layout for TOC, specifically the sidebar TOC * Example block (see http://asciidoctor.org/docs/user-manual/#example) * Sidebar block * A theme for Pygments and/or Highlight.js that matches the default stylesheet * The color of the admonition icons could also use attention * Anything you see that could be better...it's all on the table Note that the default stylesheet is generated by Compass / SASS from the stylesheet factory repository: https://github.com/asciidoctor/asciidoctor-stylesheet-factory We're limited in part by the HTML that Asciidoctor currently generates. Apart from small fixes, it might make sense to begin work on a more semantic HTML structure that will be more accommodating to styles. (See https://github.com/asciidoctor/asciidoctor/issues/242). This would open up the door for being able to create an off-canvas TOC and the like. The reason we can't do that now is that there simply aren't enough elements in the HTML to accommodate the styles. I'd also like to see a better default theme in Asciidoctor PDF (see https://github.com/asciidoctor/asciidoctor-pdf/blob/master/examples/chronicles-example.pdf). We've created a theme system that is inspired by CSS to make it comfortable for designers familiar with web development. For a (mostly complete) guide of the theming system in Asciidoctor PDF, see http://gist.asciidoctor.org/?github-asciidoctor%2Fasciidoctor-pdf%2F%2Fdocs%2Ftheming-guide.adoc. In general, I like the fonts that we are using: Open Sans - Headings Noto Serif - Body Text Droid Sans Mono - Code (HTML) M+ 1mn - Code (PDF) However, I'm open to even changing those as long as we choose fonts with an open license. I'll finish by saying that part of our philosophy in Asciidoctor is to reward writers by making it easy for them to create beautiful documentation from beautiful source. In order to achieve that goal, we need passionate designers who want to share their talents and, as a result, move the state of technical documentation forward. Thanks & cheers, |
|
Just on fonts: slab serif fonts seem to be the modern look for body text these days. One of the most successful is the Guardian newspaper (UK) website, which uses a slab serif font it had developed (example article).
This is a commercial font, but there are lots of free slab serif fonts around. I wonder if one of these could be a good body text default? |
|
In reply to this post by mojavelinux
One of the things that jumps out at me right away when looking at the CSS is actually the HTML. In the issue about semantic HTML, you mention `<div class="paragraph"><p></p></div>`. This is actually the first construct that told me that this is going to be more complex than it looks.
I see two ways to go with this: 1. Jump in and start making design improvements based on current HTML/CSS, refactoring the CSS later when the HTML changes, OR 2. Change the HTML output and then write the new CSS based on that. What are your thoughts on this? Also, since you're planning on conforming to spec, I lean toward the opinion that the default CSS should be as lean and dependent-free as possible, maybe with the exception of Sass and perhaps a normalize.css. Is there a particular reason Compass is necessary to the default? |
|
Administrator
|
Stephen, This is a very pertinent question. The lack of semantics in the default HTML output is possibly the biggest shadow that hangs over Asciidoctor land. As I mentioned in the issue {1}, the default HTML is the way it is because we aimed to stay as true as possible to the output of AsciiDoc Python to gain credibility. Recall that Asciidoctor wasn't always the leading implementation and the initial goal was to prove we could replace AsciiDoc Python. We have and it's now time to move forward. One quick fix for the paragraph situation is to port the change we made in Asciidoctor EPUB3. This change would essentially write a paragraph with a title (aka run-in head) as follows: <p><strong class="run-in-head">Title</strong> content</p> ...and in most cases, where there is no title on the paragraph, then you would just get the familiar: <p>content</p> Most of the blocks (example, sidebar, etc) use a nested structure to accommodate the title / caption element. A lot of the default stylesheet deals with how these combinations interact. For instance, see: In fact, a lot of the CSS rules need to bend over backwards to work with the non-semantic structure of the HTML. If we had more elements and more classes, then it would drastically simplify the styling task (for instance, I did the Asciidoctor EPUB3 stylesheet by hand). Perhaps you can appreciate the lengths I had to go to in order to achieve the current consistency in the default stylesheet ;) There's no question we need to move to a semantic HTML structure. The first (and rather interesting) step to take is probably to start working on that HTML structure. I talked with Anthonny and Maxime about this when I was in France this past Spring. Anthonny needs more semantic HTML for HubPress.io so it's easier to create themes for that interface. Fortunately, a lot of work has already been done in the Asciidoctor EPUB3 converter {2}. That HTML this much more semantic than the default HTML. But, by no means am I calling it finished. I do agree. I reached into the bag and grabbed Foundation because it got me going quickly when the goal was to get something out there. Since then, the stylesheet has evolved quite a bit and we actually override a lot of elements that Foundation provides. I'm not going to say it doesn't provide value, because it does, but I do believe whether or not to use it is the designer's call. We'll still need Foundation (I think) for people to create custom stylesheets, but it isn't mandatory for the default stylesheet. In fact, the smaller the better. > Is there a particular reason Compass is necessary to the default? I don't think we're really using Compass other than as a build mechanism. If you look at what we import, all we take is the box-shadow, and that could be replaced. All I really want to use is Sass. I'd even be okay with using a subset of normalize.css, because we don't even need all the defaults it sets (as we don't have any forms). I hope that provides some necessary direction. I think the time is right to start the effort on the semantic HTML and just plan to style that result. Why continue investing too much in the old HTML, unless it's patches to align a few colors here and there? When we create the revised HTML structure and styles, keep in mind that AsciiDoc output has two modes, standalone (full) and embeddable. One of the issues I still have is to rework the stylesheet so that I can split out a partial CSS file that can be applied to the embeddable HTML {3}. It's good to keep this in mind from the start. Cheers, -Dan On Sun, Jul 12, 2015 at 2:36 PM, stephenhay [via Asciidoctor :: Discussion] <[hidden email]> wrote: One of the things that jumps out at me right away when looking at the CSS is actually the HTML. In the issue about semantic HTML, you mention `<div class="paragraph"><p></p></div>`. This is actually the first construct that told me that this is going to be more complex than it looks. Dan Allen | http://google.com/profiles/dan.j.allen |
|
Administrator
|
In reply to this post by stephenhay
On Mon, Jul 13, 2015 at 2:17 AM, Dan Allen <[hidden email]> wrote: I do believe whether or not to use it is the designer's call. And I do dream of one day having a design team within the Asciidoctor project, because to be truly great at creating beautiful documentation, we have to solve hard, real-world design problems. But don't worry, there's plenty of stuff on the surface to address before it gets too hairy :) |
|
Administrator
|
In reply to this post by stephenhay
On Sun, Jul 12, 2015 at 2:36 PM, stephenhay [via Asciidoctor :: Discussion] <[hidden email]> wrote:
There's also the infamous "paragraph in list item issue" {1} which affects rendering where the stylesheet is not available, such as on GitHub. Again, I think we've solved this in Asciidoctor EPUB3 by turning the primary list content into a span as: <ul> <li><span class="principle">item text</span></li> ... </ul> These are the types of changes we'll need in addition to the obvious stuff like using the <section> element for sections. Cheers, -Dan |
«
Return to Asciidoctor :: Discussion
|
1 view|%1 views
| Free forum by Nabble | Edit this page |