SkillHub ClubShip Full StackFull Stack

moai-lang-html-css

Imported from https://github.com/dolsoon/my-awesome-project.

Packaged view

This page reorganizes the original catalog entry around fit, installability, and workflow context first. The original raw source lives below.

Stars

Hot score

Updated

March 20, 2026

Overall rating

C2.7

Composite score

2.7

Best-practice grade

B75.1

Install command

npx @skill-hub/cli install dolsoon-my-awesome-project-moai-lang-html-css

Repository

dolsoon/my-awesome-project

Skill path: .claude/skills/moai-lang-html-css

Imported from https://github.com/dolsoon/my-awesome-project.

Open repository

Best for

Primary workflow: Ship Full Stack.

Technical facets: Full Stack.

Target audience: everyone.

License: Unknown.

Original source

Catalog source: SkillHub Club.

Repository owner: dolsoon.

This is still a mirrored public skill entry. Review the repository before installing into production workflows.

What it helps with

Install moai-lang-html-css into Claude Code, Codex CLI, Gemini CLI, or OpenCode workflows
Review https://github.com/dolsoon/my-awesome-project before adding moai-lang-html-css to shared team environments
Use moai-lang-html-css for development workflows

Works across

Claude CodeCodex CLIGemini CLIOpenCode

Favorites: 0.

Sub-skills: 0.

Aggregator: No.

Original source / Raw SKILL.md

---
name: "moai-lang-html-css"
version: "4.0.0"
status: stable
description: "Enterprise Skill for advanced development"
allowed-tools: "Read, Bash, WebSearch, WebFetch"
---

# moai-lang-html-css

**HTML5 Semantic Markup & CSS Best Practices with Accessibility Focus**

> **Primary Agent**: ui-ux-expert
> **Secondary Agent**: frontend-expert
> **Version**: 1.0.0
> **Keywords**: html, semantic html, html5, css, styling, accessibility, a11y, wcag, responsive, semantics

---

## 📖 Progressive Disclosure

### Level 1: Quick Reference (Core Concepts)

**HTML Semantic Elements** form the foundation of accessible, SEO-friendly web pages:

| Element | Purpose | Use Case |
|---------|---------|----------|
| `<header>` | Page/section header | Logo, navigation, branding |
| `<nav>` | Navigation container | Menu, breadcrumbs, site links |
| `<main>` | Primary content | Main page content (only one per page) |
| `<section>` | Thematic content group | Articles, chapters, topics |
| `<article>` | Self-contained content | Blog posts, news articles, comments |
| `<aside>` | Tangentially related content | Sidebars, ads, related links |
| `<footer>` | Footer section | Copyright, links, metadata |

**CSS Best Practices**:
- ✅ Mobile-first responsive design (min-width breakpoints)
- ✅ CSS custom properties for design tokens
- ✅ Utility-first approach (Tailwind) or BEM methodology
- ✅ Avoid inline styles; use classes
- ✅ Minimize CSS specificity (avoid `!important`)

**WCAG 2.1 AA Accessibility Checklist**:
- 4.5:1 color contrast for text
- Keyboard navigation (Tab, Enter, Escape, Arrow keys)
- Focus indicators (2px solid outline)
- Semantic HTML (no `<div>` for buttons)
- ARIA labels where necessary

---

### Level 2: Practical Implementation (Common Patterns)

#### Pattern 1: Semantic HTML Page Structure

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Accessible Web Page</title>
  <link rel="stylesheet" href="styles.css">
</head>
<body>
  <!-- Page Header -->
  <header role="banner">
    <nav role="navigation" aria-label="Main navigation">
      <a href="/" class="logo">Brand</a>
      <ul>
        <li><a href="/about">About</a></li>
        <li><a href="/services">Services</a></li>
        <li><a href="/contact">Contact</a></li>
      </ul>
    </nav>
  </header>

  <!-- Skip Link (accessibility best practice) -->
  <a href="#main" class="sr-only">Skip to main content</a>

  <!-- Main Content -->
  <main id="main" role="main">
    <!-- Article Section -->
    <article>
      <h1>Article Title</h1>
      <p>Article introduction...</p>
      <section>
        <h2>Section Heading</h2>
        <p>Section content...</p>
      </section>
    </article>

    <!-- Sidebar -->
    <aside aria-label="Related content">
      <h3>Related Articles</h3>
      <ul>
        <li><a href="...">Related article 1</a></li>
        <li><a href="...">Related article 2</a></li>
      </ul>
    </aside>
  </main>

  <!-- Page Footer -->
  <footer role="contentinfo">
    <p>&copy; 2025 Company Name. All rights reserved.</p>
  </footer>
</body>
</html>
```

#### Pattern 2: Accessible Form with Labels

```html
<!-- WCAG 2.1 AA Compliant Form -->
<form method="POST" action="/submit">
  <fieldset>
    <legend>Contact Information</legend>

    <!-- Email Input with Label -->
    <div class="form-group">
      <label for="email">Email Address *</label>
      <input
        id="email"
        type="email"
        name="email"
        required
        aria-required="true"
        aria-describedby="email-help"
      >
      <small id="email-help">We'll never share your email</small>
    </div>

    <!-- Text Area -->
    <div class="form-group">
      <label for="message">Message *</label>
      <textarea
        id="message"
        name="message"
        rows="5"
        required
        aria-required="true"
      ></textarea>
    </div>

    <!-- Error Message (live region) -->
    <div role="alert" aria-live="polite" id="form-error">
      <!-- Error messages inserted here -->
    </div>

    <!-- Submit Button -->
    <button type="submit" class="btn btn-primary">
      Send Message
    </button>
  </fieldset>
</form>
```

#### Pattern 3: Responsive CSS with Custom Properties

```css
/* Design Tokens as CSS Custom Properties */
:root {
  /* Colors */
  --color-primary: #0ea5e9;
  --color-primary-dark: #0284c7;
  --color-secondary: #8b5cf6;
  --color-neutral-900: #111827;
  --color-neutral-500: #6b7280;
  --color-neutral-100: #f3f4f6;

  /* Typography */
  --font-family-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
  --font-family-mono: "Monaco", "Menlo", "Ubuntu Mono", monospace;
  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;
  --font-size-xl: 1.25rem;
  --font-size-2xl: 1.5rem;
  --font-weight-normal: 400;
  --font-weight-medium: 500;
  --font-weight-bold: 700;

  /* Spacing (8px base unit) */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 2rem;
  --spacing-2xl: 3rem;

  /* Breakpoints */
  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
  --breakpoint-xl: 1280px;

  /* Shadows */
  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
  --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
  --shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);
}

/* Base Styles */
html {
  scroll-behavior: smooth;
}

body {
  font-family: var(--font-family-sans);
  font-size: var(--font-size-base);
  color: var(--color-neutral-900);
  line-height: 1.5;
  -webkit-font-smoothing: antialiased;
}

/* Typography */
h1, h2, h3, h4, h5, h6 {
  font-weight: var(--font-weight-bold);
  line-height: 1.2;
}

h1 {
  font-size: var(--font-size-2xl);
  margin-bottom: var(--spacing-lg);
}

h2 {
  font-size: var(--font-size-xl);
  margin-bottom: var(--spacing-md);
}

p {
  margin-bottom: var(--spacing-md);
}

/* Button Component */
.btn {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  padding: var(--spacing-sm) var(--spacing-md);
  font-weight: var(--font-weight-medium);
  border: none;
  border-radius: 0.375rem;
  cursor: pointer;
  transition: all 0.2s ease;

  /* Focus indicator (WCAG AA) */
  outline: none;
}

.btn:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
}

.btn:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

.btn-primary {
  background-color: var(--color-primary);
  color: white;
}

.btn-primary:hover {
  background-color: var(--color-primary-dark);
}

/* Form Group */
.form-group {
  margin-bottom: var(--spacing-lg);
}

label {
  display: block;
  font-weight: var(--font-weight-medium);
  margin-bottom: var(--spacing-sm);
}

input, textarea, select {
  width: 100%;
  padding: var(--spacing-sm) var(--spacing-md);
  border: 1px solid var(--color-neutral-300);
  border-radius: 0.375rem;
  font-family: inherit;
  font-size: inherit;
}

input:focus, textarea:focus, select:focus {
  outline: none;
  border-color: var(--color-primary);
  box-shadow: 0 0 0 3px rgba(14, 165, 233, 0.1);
}

input:invalid {
  border-color: #ef4444;
}

/* Responsive Grid (Mobile-First) */
.grid {
  display: grid;
  gap: var(--spacing-md);
}

@media (min-width: var(--breakpoint-md)) {
  .grid {
    grid-template-columns: repeat(2, 1fr);
  }
}

@media (min-width: var(--breakpoint-lg)) {
  .grid {
    grid-template-columns: repeat(3, 1fr);
  }
}

/* Screen Reader Only (a11y) */
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

/* Focus Visible (keyboard accessibility) */
:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
}
```

---

### Level 3: Advanced Patterns (Expert Reference)

#### Advanced Pattern 1: Accessible Modal Dialog

```html
<div role="dialog"
     aria-modal="true"
     aria-labelledby="modal-title"
     aria-describedby="modal-description">
  <div class="modal-overlay" onclick="closeModal()"></div>
  <div class="modal-content">
    <button
      class="modal-close"
      aria-label="Close dialog"
      onclick="closeModal()">
      ✕
    </button>
    <h2 id="modal-title">Dialog Title</h2>
    <p id="modal-description">Dialog description...</p>
    <button class="btn btn-primary">Action</button>
  </div>
</div>

<style>
  [role="dialog"] {
    position: fixed;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
    display: flex;
    align-items: center;
    justify-content: center;
    z-index: 50;
  }

  .modal-overlay {
    position: absolute;
    inset: 0;
    background-color: rgba(0, 0, 0, 0.5);
  }

  .modal-content {
    position: relative;
    background: white;
    border-radius: 0.5rem;
    padding: 2rem;
    max-width: 500px;
    box-shadow: 0 20px 25px rgba(0, 0, 0, 0.15);
  }

  /* Focus trap for keyboard users */
  [role="dialog"]:focus-within .modal-content {
    outline: 2px solid var(--color-primary);
  }
</style>

<script>
  function closeModal() {
    const dialog = document.querySelector('[role="dialog"]');
    dialog.remove();
    // Restore focus to trigger element
    previousFocusElement?.focus();
  }

  // Focus trap (prevent Tab from leaving modal)
  document.addEventListener('keydown', (e) => {
    if (e.key === 'Escape') closeModal();
  });
</script>
```

#### Advanced Pattern 2: Skip Navigation (A11y Best Practice)

```html
<!-- Place at very beginning of <body> -->
<a href="#main" class="sr-only skip-link">Skip to main content</a>

<style>
  .skip-link {
    position: absolute;
    top: -40px;
    left: 0;
    background: var(--color-primary);
    color: white;
    padding: 0.5rem 1rem;
    text-decoration: none;
    z-index: 100;
  }

  .skip-link:focus {
    top: 0;
  }
</style>
```

---

## 🎯 Best Practices Checklist

### HTML
- ✅ Use semantic HTML5 elements (`<header>`, `<nav>`, `<main>`, `<section>`, `<article>`, `<aside>`, `<footer>`)
- ✅ Proper heading hierarchy (`<h1>` → `<h2>` → `<h3>`, never skip levels)
- ✅ Form labels explicitly connected with `<label for="id">` and `input id="id"`
- ✅ Alternative text for all images: `<img alt="description">`
- ✅ Landmark roles for screen readers: `role="banner"`, `role="main"`, `role="contentinfo"`

### CSS
- ✅ Mobile-first responsive design (start at mobile, add styles for larger screens)
- ✅ Use CSS custom properties for design tokens (colors, spacing, typography)
- ✅ Maintain 4.5:1 color contrast for normal text (WCAG AA)
- ✅ Visible focus indicators for keyboard users (`:focus-visible`, 2px outline)
- ✅ Use `rem` or `em` for sizing (not `px`) for better font scaling

### Accessibility (WCAG 2.1 AA)
- ✅ Color contrast: Text 4.5:1, UI components 3:1 (use WebAIM contrast checker)
- ✅ Keyboard navigation: All functionality accessible via Tab, Enter, Escape, arrow keys
- ✅ Focus visible: Clear focus indicators (2px solid outline preferred)
- ✅ Semantic HTML foundation: Proper heading levels, form labels, alt text
- ✅ ARIA only when semantic HTML insufficient: `aria-label`, `aria-describedby`, `role="alert"`
- ✅ Skip links: Allow skipping repetitive navigation

---

## 📚 Official References

- **W3C HTML5 Spec**: https://html.spec.whatwg.org/
- **WCAG 2.1 Guidelines**: https://www.w3.org/WAI/WCAG21/quickref/
- **MDN Web Docs - HTML**: https://developer.mozilla.org/en-US/docs/Web/HTML
- **MDN Web Docs - CSS**: https://developer.mozilla.org/en-US/docs/Web/CSS
- **WebAIM - Contrast Checker**: https://webaim.org/resources/contrastchecker/
- **WAI-ARIA Authoring Practices**: https://www.w3.org/WAI/ARIA/apg/

---

## 🔗 Related Skills

- `Skill("moai-lang-tailwind-css")` – Utility-first CSS framework
- `Skill("moai-lib-shadcn-ui")` – React components with Tailwind + Radix
- `Skill("moai-domain-frontend")` – Full frontend architecture