AI Skill Report Card
Applying Alibaba HTML Spec
YAML--- name: applying-alibaba-html-spec description: Reviews and writes HTML markup according to the Alibaba front-end coding specification, covering document structure, encoding rules, tag/attribute formatting, semantics, accessibility, and template language conventions. Use when writing new HTML files, reviewing HTML/template code for compliance, or setting up front-end project boilerplate that needs to follow Alibaba's style guide. ---
Quick Start14 / 15
Standard compliant HTML boilerplate:
HTML<!doctype html> <html lang="en-US"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1" /> <title>My Site - There are a lot of fun!</title> <meta name="description" content="web front-end coding and engineering specification" /> <meta name="keyword" content="code,html,css,javascript,typescript,react,node" /> <link rel="stylesheet" href="index.css" /> </head> <body> <div id="root"></div> <script src="./index.js"></script> </body> </html>
Recommendation▾
Add a third example showing template language escaping in context to reinforce that specific rule
Workflow14 / 15
When writing or reviewing HTML, check items in this order:
Progress:
- [ ] Document structure: doctype, single <html>/<head>/<body>, lang attribute
- [ ] Meta tags: charset, viewport (inside <head> only)
- [ ] Resource loading: CSS in <head>, JS before </body>, protocol-relative URLs
- [ ] Title: exactly one <title>
- [ ] Indentation: 2 spaces, no tabs
- [ ] Comments: no sensitive info, correct spacing format
- [ ] Tags: lowercase, self-closing tags keep " />"
- [ ] Attributes: double quotes, no Boolean value assignment, data- prefix for custom attrs
- [ ] Semantics: correct elements for content meaning (ul/li vs div, etc.)
- [ ] Accessibility: alt text on images, meaningful roles
- [ ] Template language: spacing around variables/filters, escaping user input
Recommendation▾
Include a bad/before-and-after example specifically for accessibility rules (alt text, roles) since it's only covered abstractly
Rules Reference
Document Structure (Enforced)
- Must start with
<!doctype html>(lowercase, HTML5 form only — no XHTML/HTML4 doctypes). - Exactly one top-level
<html>element. <html>must have alangattribute inlanguage-REGIONformat (e.g.en-US,zh-CN), neverzh_CNorzh-cn.- If part of the content is in a different language, add
langto that sub-element (e.g.<footer lang="en-US">). <html>contains exactly one<head>and one<body>— nothing outside them (no stray<script>after</body>).<meta>elements must live inside<head>.- Must use
<meta charset="utf-8" />. - Exactly one
<title>element.
Viewport (Recommended)
HTML<meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1" />
Disable pinch-zoom only if the UI has its own zoom gestures:
HTML<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no" />
Resource Loading (Recommended)
- Omit
typefor<link rel="stylesheet">,<style>,<script>—text/css/text/javascriptare defaults. - Put CSS
<link>/<style>in<head>; put<script>right before</body>(except scripts that must run before DOM load, e.g. polyfills/base libs). - External resource URLs should be protocol-relative:
//g.alicdn.com/lib/style/index-min.css. - Use
<link rel="preload" as="...">for critical resources. - Use
dns-prefetch/preconnectfor early DNS resolution of cross-origin hosts.
Formatting
- Indentation: 2 spaces, never 4 spaces or tabs.
- Tag names lowercase:
<h1>not<H1>. - Keep the self-closing slash with a preceding space:
<img src="foo.png" alt="foo" />. - Attribute values use double quotes only.
- Boolean attributes take no value:
disabled,checked,selected(notdisabled="disabled"). - Custom attributes prefixed with
data-:data-modal="toggle".
Comments (Enforced)
- No sensitive info in HTML comments: business rules, PII (email/phone/ID numbers), access keys, certificates/passwords, internal IPs/URLs, or other internal-only company info.
- Single-line: one space between
<!--and content, and content and-->. - Multi-line: opening/closing markers on their own line, content indented 2 spaces.
Semantics & Accessibility (Recommended/Reference)
- Prefer semantic elements over generic
div/spanwhen meaning exists: use<ul><li>for lists,<p>for paragraphs,<a>for links/anchors. - Always set meaningful
alton<img>; usealt=""orrole="presentation"for purely decorative images.
Template Languages (e.g. Nunjucks) (Enforced)
- Space around variables, filters, keywords:
{{ username }},{{ tags | join(',') }}— not{{username}}. - All unescaped/untrusted user input must be HTML-escaped before output, including inside
<script>blocks:{{ description | escaped }},window.user = {{ user | dump | escaped }}.
Examples17 / 20
Example 1: Input:
HTML<HTML> <head><meta charset=utf-8> <title>Page</title> <script type="text/javascript" src='app.js'></script> </head> <body> <div class="list"><div>1</div><div>2</div></div> <img src="logo.png"> </body> </HTML>
Output:
HTML<!doctype html> <html lang="en-US"> <head> <meta charset="utf-8" /> <title>Page</title> </head> <body> <ul class="list"> <li>1</li> <li>2</li> </ul> <img src="logo.png" alt="" /> <script src="app.js"></script> </body> </html>
Example 2:
Input: <input type="checkbox" checked="checked" data-toggle='foo'>
Output: <input type="checkbox" checked data-toggle="foo" />
Recommendation▾
Consider a brief note on how to handle conflicting enforced vs recommended rules during review for edge-case prioritization
Best Practices
- Default to protocol-relative URLs (
//...) for CDN resources. - When in doubt about tag choice, pick the most semantically accurate HTML5 element.
- Treat "Enforced" (强制) rules as hard errors during review; "Recommended"/"Reference" as strong suggestions to flag but not necessarily block on.
Common Pitfalls
- Forgetting
langon<html>or using underscore instead of hyphen (zh_CNvszh-CN). - Placing
<meta>or<script>(base libs aside) in<body>unnecessarily, causing reflow/render-blocking. - Using single quotes for attribute values.
- Adding explicit values to Boolean attributes.
- Leaving
altoff images entirely instead of usingalt=""for decorative ones. - Outputting unescaped user input into HTML or inline
<script>blocks — always escape.