You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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
Best practices (focus states, color contrast mentions, screen reader tips)
Deliverables
index.mdx section 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>]
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'>]
Loading
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
Loading
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))
Loading
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]
Loading
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]
Loading
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
Is there an existing issue for this?
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>2. Global & Element-Specific Attributes
Document attributes such as
id,class,title,lang,dir,tabindexhref,src,alt,targetdisabled,required,readonlyInclude tables, examples, and usage guidelines.
3. Forms & Input Structure
Include:
<form>usage and structuretext,email,number,date, etc.)<label>association (for, id, nesting)4. Accessibility & ARIA Roles
Develop rich content covering:
button,alert,navigation,dialog, etc.)aria-label,aria-labelledby,aria-hidden,aria-expanded)Deliverables
index.mdxsection for HTML RoadmapQuality Checklist
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-selected3. 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 result5. 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