Rework HTML Style Guide #92

sfrisk · 2014-11-12T23:27:51Z

The current html style guide is very limited (http://contribute.jquery.org/style-guide/html/). Rework html style guide to be more robust to handle future development for html heavy projects.

scottgonzalez · 2014-11-13T00:25:29Z

Please provide specific things that you think are missing. Broad issues with no details can't be acted on.

sfrisk · 2014-11-13T01:01:45Z

Will do. Created this more to tie in with discussions over on css-framework. If it follows procedure better, I can close this task out, and open a new one when a more in depth discussion of what needs to get added has taken place.

sfrisk · 2014-11-13T02:02:44Z

Suggested items to add/address in the current html style guide.

whitespace nesting line breaks
validation of html
use of inline js onclick attributes
use of inline style attributes
perhaps some rules on commenting (unless we want to address all commenting rules in a separate backlog)
maybe something on accessible markup, especially when it comes to forms/images/etc?
multimedia fallback (alt text for images)
update indentation rules (do we really not want to allow any indenting inside the body tag? Because that could result in making html less readable, unless I'm reading the indentation rules and example wrong. In which case, maybe clarify it a bit)
Use double quotation marks over single quotation marks.

scottgonzalez · 2014-11-13T12:58:06Z

whitespace nesting line breaks

I'm not sure what that means. Can you give an example?

validation of html

It should be valid. I guess we can explicitly state that.

use of inline js onclick attributes

We shouldn't allow on* attributes at all.

use of inline style attributes

Should be avoided, but acceptable in some situations.

perhaps some rules on commenting (unless we want to address all commenting rules in a separate backlog)

No rules.

maybe something on accessible markup, especially when it comes to forms/images/etc?

Everything should be accessible. This will be nearly impossible to document other than just saying that it should be accessible.

multimedia fallback (alt text for images)

At least for images, a missing alt attribute is invalid.

update indentation rules (do we really not want to allow any indenting inside the body tag? Because that could result in making html less readable, unless I'm reading the indentation rules and example wrong. In which case, maybe clarify it a bit)

You're probably reading them wrong. You do not indent inside <body>, but that doesn't mean there is no indenting inside its children.

Use double quotation marks over single quotation marks.

Generally, yes.

arschmitz · 2014-11-13T13:02:14Z

@scottgonzalez while yes there are very simple answers to these things none of this is actually in the style guide and probably should be.

whitespace nesting line breaks

I think this is probably 3 different things, whitespace, nesting, and linebreaks

arschmitz · 2014-11-13T13:04:33Z

Also since UI uses HTML lint and we are adding this to mobile I'd like to see lint settings.

sfrisk · 2014-11-13T14:40:12Z

As @arschmitz said, I made the list more as a suggestion of things to add to html style guide. While some of them might be common sense (such as valid html), we still aren't covering the above items at all/ at in the level of depth we do in other style guides. If we're going to be working on more potentially html heavy projects (such as css framework), expanding the html style guide to include the above items could potentially help with PRs.

With the <body> indentation item, I was mostly confused with the html example given, and I wasn't sure if it was saying nothing could be indented or not.

scottgonzalez · 2014-11-13T14:43:04Z

My responses were just meant as my answers to what should be documented for each section, not that they don't belong in the style guide. For the <body> indentation example, we can certainly just add more markup to show that it's only the first level of indentation that doesn't exist.

arschmitz · 2014-11-13T14:43:39Z

In the example there should be some nested elements to make this clear, not just a single paragraph in the body, this is not a clear example in my opinion. Also the wording Indentation
"Don't indent inside html, body, script, or style. Indent inside head and all other elements." is not clear at all.

sfrisk · 2014-11-13T14:43:39Z

Ahh, okay. Was just clarifying, since I wasn't quite sure.

arschmitz · 2014-11-13T14:43:53Z

@scottgonzalez Bah you beat me timing...

sfrisk · 2014-11-13T14:44:32Z

However, since we have a list of action items to work off of for the html style guide, I can start working on it.

MichaelArestad · 2015-01-22T02:52:08Z

Accessibility

maybe something on accessible markup, especially when it comes to forms/images/etc?

I would definitely include references to proper accessible markup and how to properly write an alt attribute.

Maybe something about tabindex as well.

I would potentially add a bit about adding <title> and <desc> elements to inline SVGs.#

Forms
I would include:

proper locations for label element in conjunction with various input types.
proper use of placeholder text

handasolo · 2015-03-23T21:37:59Z

http://validator.w3.org/ can be used for html validation ?

arschmitz · 2015-03-23T21:58:14Z

@Slayslot this is about style not validity

handasolo · 2015-03-24T07:47:36Z

@arschmitz Yes, but @sfrisk had it in her suggested items list, so if we're going to explicitly ask the users to write valid html why not recommend them to check it from here as well? Google does the same thing in their HTML style guide. https://google-styleguide.googlecode.com/svn/trunk/htmlcssguide.xml#HTML_Validity

scottgonzalez · 2015-03-24T13:02:28Z

Just a note about validators: While validator.w3.org is certainly useful, we do use validator.nu for our automated testing via grunt-html.

sfrisk · 2015-03-24T13:15:47Z

It might be useful to list our preference for validator.nu in the html style guide, but in general the HTML style guide should focus more on style since we're looking to expand the HTML style guide to be similar to the CSS/JS ones.

handasolo · 2015-03-24T14:16:15Z

So we can just mention that we use validator.nu for automated testing via grunt-html and further recommend them to use it before posting html.

scottgonzalez · 2015-03-24T14:23:09Z

Before posting what HTML? If it's a project that's using grunt-html, it will automatically be checked. Having to manually check validation is extremely tedious and time consuming.

handasolo · 2015-03-24T14:48:02Z

I've been reading Code Guide and Google's HTML style guide and have come up with the following things that should be included in the style guide:

Remove Trailing Whitespace.
Separation of Concerns (No inline styles or scripts).
HTML semantics(Using proper HTML elements wherever needed).
Attributes to be placed in order(This will increase readability.Order is mentioned after the list).
Reducing Markup(Avoid superfluous parent elements).
Avoid JS Generated Markup.
Not separating attributes with two or more white spaces.
Line break after br element.
Wrapping form control with label element.
Using appropriate type element for input element.
Add value attribute to input type="submit".
Not using placeholder for labelling.

The Attribute order being:

class
id,name
data-*
src,for,type,href,value
title,alt,
aria-*,role

Edit 1:

Just adding some things that I forgot to add. These are the ones I'm still in dilemma of.
Should we omit protocol or not?
Two space indentation or tabs?
Add script tags before closing of body or in the head?
Adding title attribute to alternate stylesheets?

and this last one is something I liked but I don't know how useful it is. Adding TODOs in comments just as mentioned in Google's HTML style guide. We can append a contact in parenthesis and action items after a colon.

scottgonzalez · 2015-03-24T14:55:32Z

Wrapping form control with label element.

We need evidence this is a good idea. This has historically been bad for accessibility.

Using appropriate type element for input element.

You mean type attribute. This isn't necessary for text fields, but it depends if you want to easily target text inputs via CSS.

Add value attribute to input type="submit".

Only needed if you're using multiple submit elements on the same form.

The Attribute order being:

Is there an explanation of why this order is chosen?

handasolo · 2015-03-24T19:32:25Z

Before posting what HTML? If it's a project that's using grunt-html, it will automatically be checked. Having to manually check validation is extremely tedious and time consuming.

Point taken.

We need evidence this is a good idea. This has historically been bad for accessibility.

I, quite frankly didn't know that. On a bit research I found this . So at least radio buttons and checkboxes take advantage from this method.

You mean type attribute. This isn't necessary for text fields, but it depends if you want to easily target text inputs via CSS.

Would it hurt if a type attribute is included for text field? I'm honestly asking here? Because if it won't hurt then it only makes it easier for everyone to write and understand. Similarly I couldn't understand the Indentation section from the existing HTML style guide. Don't indent inside html, body, script, or style. Indent inside head and all other elements Why not indent inside html,body,script and style? I get that if you're using tabs it might push the content further right and in turn decrease readability. But, if we use 2 spaces to indent instead of tab, wouldn't that make reading and writing more consistent? You indent inside every element and indent with only 2 spaces. Sweet and simple.

Is there an explanation of why this order is chosen?

Well, let me just quote Codeguide Classes make for great reusable components, so they come first. Ids are more specific and should be used sparingly (e.g., for in-page bookmarks), so they come second. No further explanation is given. I feel that any logical order can be decided upon just to create a standard people can familiarize themselves around which will in turn lead towards better readability.

scottgonzalez · 2015-03-24T19:41:30Z

I, quite frankly didn't know that. On a bit research I found this . So at least radio buttons and checkboxes take advantage from this method.

That answer says nothing about accessibility, but note that the comments on the answer say to use the for attribute rather than relying on implicit association via wrapping.

Would it hurt if a type attribute is included for text field?

It doesn't hurt, it's just not necessary. It's the same as explicitly passing the same values as default options in your JavaScript.

Why not indent inside html,body,script and style?

Because it doesn't actually improve readability and instead just pushes everything further out.

But, if we use 2 spaces to indent instead of tab, wouldn't that make reading and writing more consistent?

I'll go on record as saying that I would absolutely hate for any of our style guides to require 2 spaces. I honestly don't understand how the world hasn't settled on tabs by now.

dmethvin · 2015-03-24T19:50:46Z

Would it hurt if a type attribute is included for text field?

It doesn't hurt, it's just not necessary.

As you noted though, it's necessary if you want to style text inputs since <input /> won't match a CSS rule of input[type=text].

handasolo · 2015-03-24T20:28:17Z

That answer says nothing about accessibility, but note that the comments on the answer say to use the for attribute rather than relying on implicit association via wrapping.

I was focusing more on the increased hit zone but I do get your point. What, in your opinion, would be the best way for this?

It doesn't hurt, it's just not necessary. It's the same as explicitly passing the same values as default options in your JavaScript.

okay, but this extra effort will make it easier to style them in CSS.

I'll go on record as saying that I would absolutely hate for any of our style guides to require 2 spaces. I honestly don't understand how the world hasn't settled on tabs by now.

Frankly speaking, I too use tabs. And, now that you've pointed out your hate for 2 spaces I realize that I hated it too. For the fact that the deeper the element, that you're working on, is nested the tedious it gets to add spaces. Adding 2*n spaces after every line will obviously be tedious than adding n tabs. I would really like to see others view on this and the second list I've added in my comments edit. As both of these have their pros and cons.

scottgonzalez · 2015-03-24T21:38:52Z

I was focusing more on the increased hit zone but I do get your point. What, in your opinion, would be the best way for this?

Keep them separate and use the for attribute.

okay, but this extra effort will make it easier to style them in CSS.

I would prefer if we didn't require type attributes, but I'm not strongly against it if we have a tool that's checking for it.

handasolo · 2015-03-25T18:37:15Z

Keep them separate and use the for attribute.

Alright, we can keep that.

I would prefer if we didn't require type attributes, but I'm not strongly against it if we have a tool that's checking for it.

HTML validation wouldn't check for that?

scottgonzalez · 2015-03-25T18:56:19Z

HTML validation wouldn't check for that?

I'm not aware of any validator that checks for an optional attribute to be required.

handasolo · 2015-03-25T19:27:25Z

I'm not aware of any validator that checks for an optional attribute to be required.

Hmm, didn't think so. This will be problematic then.

handasolo · 2015-03-29T17:53:30Z

Just to move things further and for everyone's ease I've made these lists consisting everything that has been discussed here so far.

Changes that nobody has any objection against:

Remove Trailing Whitespace.
Separation of Concerns (No inline styles or scripts).
HTML semantics(Using proper HTML elements wherever needed).
Attributes to be placed in order(Order to be decided).
Reducing Markup(Avoid superfluous parent elements).
Avoid JS Generated Markup.
Not separating attributes with two or more white spaces.
Line break after br element.
Using for in label.
Not using placeholder for labelling.
alt text for images.
double quotation over single quotation
No use of on* attributes.

Changes that have had no discussion:

Should we omit protocol or not?
Adding title attribute to alternate stylesheets?
Using TODO in comments.

Changes with conflict:

Using appropriate type element for input element: Need a tool to check for it.
Two space indentation or tabs? : Both have their advantages and disadvantages.

scottgonzalez · 2015-03-29T21:56:12Z

Attributes to be placed in order(Order to be decided).

I'm not really convinced an order is necessary. There are a few attributes (rel, type, src, href) that I think should always be in the front, but I don't really see much value in defining extensive orders.

Avoid JS Generated Markup.

I'm not really sure how this is tied to an HTML style guide.

Line break after br element.

I'm not sure what the intention is. <br> elements are pretty rare in good markup, I'm not sure this requires an explicit rules.

No use of on* attributes.

How is this different from separation of concerns?

Should we omit protocol or not?

That's a highly dependent question, isn't it?

Adding title attribute to alternate stylesheets?

Why?

Using TODO in comments.

If it's a TODO, yes. I don't see why this would be included in a style guide.

Two space indentation or tabs? : Both have their advantages and disadvantages.

I would expect that jQuery projects won't follow the style guide if the rule isn't tabs.

scottgonzalez · 2015-03-29T22:00:22Z

Two space indentation or tabs? : Both have their advantages and disadvantages.

I would expect that jQuery projects won't follow the style guide if the rule isn't tabs.

Phrased another way: Every project that this is intended to apply to already has a rule to use tabs.

handasolo · 2015-03-31T21:11:34Z

I'm not really convinced an order is necessary. There are a few attributes (rel, type, src, href) that I think should always be in the front, but I don't really see much value in defining extensive orders.

Alright, if not an extensive order at least we can tell people to keep the few attributes that you stated(and maybe add class to that?) in the front.

I'm not really sure how this is tied to an HTML style guide.

include it in the JS guide then?

I'm not sure what the intention is.
elements are pretty rare in good markup, I'm not sure this requires an explicit rules.

Makes sense.

How is this different from separation of concerns?

That's my bad.

That's a highly dependent question, isn't it?

Dependent on whether the asset is available for both protocols?

Why?

To make it clear as to what the alternate stylesheet is there for. I am not sure if this is entirely necessary or if it will help in any way, hence, it was placed in the dilemma list.

If it's a TODO, yes. I don't see why this would be included in a style guide.

To define a proper way to write TODOs. Taking the example from Google's style guide TODO(john.doe): revisit centering.

Phrased another way: Every project that this is intended to apply to already has a rule to use tabs.

Fair enough, tabs it is. But we'll have to make the wordings in the existing style guide clearer and with a better example.

scottgonzalez · 2015-03-31T21:39:57Z

Avoid JS Generated Markup.

I'm not really sure how this is tied to an HTML style guide.

include it in the JS guide then?

I'm not sure it belongs there either. This is a project by project decision. It's highly dependent on what you're trying to accomplish.

Using TODO in comments.

If it's a TODO, yes. I don't see why this would be included in a style guide.

To define a proper way to write TODOs. Taking the example from Google's style guide TODO(john.doe): revisit centering.

We don't have a single project that currently writes TODOs in that format. I think this is overkill. Most TODOs belong in issues anyway.

handasolo · 2015-03-31T22:03:53Z

I'm not sure it belongs there either. This is a project by project decision. It's highly dependent on what you're trying to accomplish.

Sure, but markup written in JS makes the markup just hard to find and edit if need be. So, if it can be avoided, then why not?

We don't have a single project that currently writes TODOs in that format. I think this is overkill. Most TODOs belong in issues anyway.

Just thought it was a decent idea. You are correct though, Most TODOs do belong in issues.

arschmitz · 2015-03-31T22:06:49Z

Sure, but markup written in JS makes the markup just hard to find and edit if need be. So, if it can be avoided, then why not?

@slayslot Because if this is to be used by projects like jQuery Mobile and UI, this makes no sense, they are projects that create JS based widgets and so intentionally generate markup. This is something that needs to be evaluated on a case by case basis, and so makes no sense in a style guide.

handasolo · 2015-04-01T08:24:58Z

@slayslot Because if this is to be used by projects like jQuery Mobile and UI, this makes no sense, they are projects that create JS based widgets and so intentionally generate markup. This is something that needs to be evaluated on a case by case basis, and so makes no sense in a style guide.

That does make sense. Don't I feel stupid now. I'll update the list.

handasolo · 2015-04-02T18:51:36Z

Before updating the list, I wanted to confirm the status of these two:

Should we omit protocol or not?
Adding title attribute to alternate stylesheets?

sfrisk mentioned this issue Nov 12, 2014

Code Style Guide jquery-archive/css-chassis#12

Open

arthurvr mentioned this issue Jun 25, 2015

New HTML Style Guide #117

Closed

scottgonzalez closed this as completed in 3e11896 Mar 11, 2016

Rework HTML Style Guide #92

Rework HTML Style Guide #92

Comments

sfrisk commented Nov 12, 2014

scottgonzalez commented Nov 13, 2014

sfrisk commented Nov 13, 2014

sfrisk commented Nov 13, 2014

scottgonzalez commented Nov 13, 2014

arschmitz commented Nov 13, 2014

arschmitz commented Nov 13, 2014

sfrisk commented Nov 13, 2014

scottgonzalez commented Nov 13, 2014

arschmitz commented Nov 13, 2014

sfrisk commented Nov 13, 2014

arschmitz commented Nov 13, 2014

sfrisk commented Nov 13, 2014

MichaelArestad commented Jan 22, 2015

handasolo commented Mar 23, 2015

arschmitz commented Mar 23, 2015

handasolo commented Mar 24, 2015

scottgonzalez commented Mar 24, 2015

sfrisk commented Mar 24, 2015

handasolo commented Mar 24, 2015

scottgonzalez commented Mar 24, 2015

handasolo commented Mar 24, 2015

scottgonzalez commented Mar 24, 2015

handasolo commented Mar 24, 2015

scottgonzalez commented Mar 24, 2015

dmethvin commented Mar 24, 2015

handasolo commented Mar 24, 2015

scottgonzalez commented Mar 24, 2015

handasolo commented Mar 25, 2015

scottgonzalez commented Mar 25, 2015

handasolo commented Mar 25, 2015

handasolo commented Mar 29, 2015

scottgonzalez commented Mar 29, 2015

scottgonzalez commented Mar 29, 2015

handasolo commented Mar 31, 2015

scottgonzalez commented Mar 31, 2015

handasolo commented Mar 31, 2015

arschmitz commented Mar 31, 2015

handasolo commented Apr 1, 2015

handasolo commented Apr 2, 2015