[Documentation Update]: html #76
Description
Is there an existing issue for this?
- I have searched the existing issues
Issue Description
Develop the foundational content for the HTML roadmap section with a primary focus on semantic structure, accessibility, and standards-based authoring. This issue covers essential topics required for beginners and intermediate learners to understand proper HTML5 semantics and accessible web markup.
Scope of Work
1. Semantic Tags & HTML5 Elements
Create explanations, examples, and best practices for:
<header>,<footer>,<nav>,<main><section>,<article>,<aside><figure>,<figcaption>- When to use semantic vs. non-semantic elements
- Benefits of semantic markup for SEO, screen readers, and maintainability
2. Global & Element-Specific Attributes
Document attributes such as
- Global:
id,class,title,lang,dir,tabindex - Functional:
href,src,alt,target - Boolean:
disabled,required,readonly - Role of attributes in accessibility, usability, and SEO
Include tables, examples, and usage guidelines.
3. Forms & Input Structure
Include:
- Proper
<form>usage and structure - Input types (
text,email,number,date, etc.) <label>association (for, id, nesting)- Fieldsets and legends
- Form validation (native + attributes)
- Accessibility considerations (ARIA, required states, instructions)
4. Accessibility & ARIA Roles
Develop rich content covering:
- What ARIA is and when to use it
- Common ARIA roles (
button,alert,navigation,dialog, etc.) - ARIA attributes (
aria-label,aria-labelledby,aria-hidden,aria-expanded) - WCAG basics
- Keyboard navigation patterns (focus order, skip links)
- Best practices (focus states, color contrast mentions, screen reader tips)
Deliverables
-
index.mdxsection for HTML Roadmap - Detailed explanations for all semantic elements
- Accessibility tables, examples, and diagrams
- Form structure examples (semantic + accessible)
- ARIA roles and usage guidelines
- Add internal links to subpages: fundamentals, accessibility, forms
- Include at least 3 diagrams (Mermaid or AI-generated)
Quality Checklist
- Content follows semantic HTML best practices
- Includes WCAG-based accessibility recommendations
- Code examples validated and formatted
- Includes real-world examples
- Easy to scan with headings, bullets, and examples
- SEO metadata added
- Mobile-friendly demonstrations included
Diagrams
1. Semantic HTML Structure Diagram
flowchart TD
A[<html>] --> B[<head>]
A --> C[<body>]
C --> D[<header>]
C --> E[<nav>]
C --> F[<main>]
C --> G[<aside>]
C --> H[<footer>]
F --> I[<section>]
F --> J[<article>]
F --> K[<figure>]
K --> L[<figcaption>]
2. Accessibility & ARIA Roles Overview
mindmap
root((ARIA))
Roles
Landmark Roles
navigation
main
banner
contentinfo
Widget Roles
button
alert
dialog
checkbox
Properties
aria-label
aria-labelledby
aria-hidden
aria-expanded
States
aria-disabled
aria-checked
aria-selected
3. HTML Form Structure Diagram
flowchart TD
A[<form>] --> B[<fieldset>]
B --> C[<legend> Form Title]
B --> D[<label for='name'>]
D --> E[<input type='text' id='name'>]
B --> F[<label for='email'>]
F --> G[<input type='email' id='email'>]
A --> H[<button type='submit'>]
4. Screen Reader Navigation Flow
sequenceDiagram
participant SR as Screen Reader
participant User
User->>SR: Start navigation (Tab/Arrow keys)
SR->>User: Reads landmark roles
SR->>User: Reads headings (H1 → H6)
SR->>User: Reads labels and inputs
SR->>User: Announces ARIA states (expanded, selected)
User->>SR: Activates elements (Enter/Space)
SR->>User: Confirms interaction result
5. Semantic vs Non-Semantic Elements
graph LR
A[Semantic Elements] --> B[<header>]
A --> C[<nav>]
A --> D[<main>]
A --> E[<article>]
A --> F[<section>]
A --> G[<footer>]
H[Non-Semantic Elements] --> I[<div>]
H --> J[<span>]
A ---|Better SEO| K((Benefits))
A ---|Accessibility| K
H ---|Requires classes| L((Limitations))
6. WCAG Accessibility Flow
flowchart TD
A[WCAG 2.1] --> B[Perceivable]
A --> C[Operable]
A --> D[Understandable]
A --> E[Robust]
B --> B1[Text Alternatives]
B --> B2[Adaptable Content]
C --> C1[Keyboard Accessible]
C --> C2[Enough Time]
D --> D1[Readable]
D --> D2[Predictable]
E --> E1[Compatible with AT]
7. ARIA Decision Flow (When to Use ARIA)
flowchart TD
A[Start] --> B{Is a native HTML element<br>available for this role?}
B -->|Yes| C[Use native HTML element]
B -->|No| D[Use ARIA role]
D --> E[Add necessary aria-* attributes]
C --> F[Follow semantic structure]
E --> F[Ensure accessibility testing]
Suggested Change
Improve clarity by adding semantic HTML examples, accessibility best practices, ARIA usage guidance, properly structured form examples, and quick-reference tables for tags and attributes. Include diagrams to visually explain structure and enhance understanding.
Rationale
This update improves clarity, teaches correct semantic HTML usage, strengthens accessibility guidance, and provides practical examples that help learners build standards-compliant, user-friendly interfaces. It ensures the documentation is accurate, modern, and aligned with best practices.
Urgency
High
Acknowledgements
- I have read the Contributing Guidelines
- I'm a GSSOC'24 contributor
- I have starred the repository
- I have read and followed the Contribution Guidelines
- I have followed the code style guidelines of this project
- I have checked for any existing open issues that my pull request may address
- I have ensured that my changes do not break any existing functionality
- Each contributor is allowed to create a maximum of 4 issues per day. This helps us manage and address issues efficiently
- I have read the resources for guidance listed below
- I have not used AI-generated content (e.g., ChatGPT, other AI tools)
- I have not used content from existing sites (e.g., text, images)
- I have followed all security rules and only shared trusted resources
Metadata
Metadata
Assignees
Type
Projects
Status