diff --git a/.codespellrc b/.codespellrc index 39d8ab1da..5e47054a8 100644 --- a/.codespellrc +++ b/.codespellrc @@ -12,6 +12,7 @@ # aline - proper name (Aline Ávila, contributor) # ative - part of "Declarative Agents" in TypeSpec M365 Copilot documentation (collections/typespec-m365-copilot.collection.md) # dateA, dateB - variable names used in sorting comparison functions -ignore-words-list = numer,wit,aks,edn,ser,ois,gir,rouge,categor,aline,ative,afterall,deques,dateA,dateB +# TE - HTTP transfer coding header +ignore-words-list = numer,wit,aks,edn,ser,ois,gir,rouge,categor,aline,ative,afterall,deques,dateA,dateB,TE # Skip certain files and directories skip = .git,node_modules,package-lock.json,*.lock,website/build,website/.docusaurus diff --git a/docs/README.skills.md b/docs/README.skills.md index c2c3090fa..5eefcc811 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -31,6 +31,7 @@ Skills differ from other primitives by supporting bundled assets (scripts, code | [azure-static-web-apps](../skills/azure-static-web-apps/SKILL.md) | Helps create, configure, and deploy Azure Static Web Apps using the SWA CLI. Use when deploying static sites to Azure, setting up SWA local development, configuring staticwebapp.config.json, adding Azure Functions APIs to SWA, or setting up GitHub Actions CI/CD for Static Web Apps. | None | | [chrome-devtools](../skills/chrome-devtools/SKILL.md) | Expert-level browser automation, debugging, and performance analysis using Chrome DevTools MCP. Use for interacting with web pages, capturing screenshots, analyzing network traffic, and profiling performance. | None | | [copilot-sdk](../skills/copilot-sdk/SKILL.md) | Build agentic applications with GitHub Copilot SDK. Use when embedding AI agents in apps, creating custom tools, implementing streaming responses, managing sessions, connecting to MCP servers, or creating custom agents. Triggers on Copilot SDK, GitHub SDK, agentic app, embed Copilot, programmable agent, MCP server, custom agent. | None | +| [create-web-form](../skills/create-web-form/SKILL.md) | Create robust, accessible web forms with best practices for HTML structure, CSS styling, JavaScript interactivity, form validation, and server-side processing. Use when asked to "create a form", "build a web form", "add a contact form", "make a signup form", or when building any HTML form with data handling. Covers PHP and Python backends, MySQL database integration, REST APIs, XML data exchange, accessibility (ARIA), and progressive web apps. | `references/accessibility.md`
`references/aria-form-role.md`
`references/css-styling.md`
`references/form-basics.md`
`references/form-controls.md`
`references/form-data-handling.md`
`references/html-form-elements.md`
`references/html-form-example.md`
`references/hypertext-transfer-protocol.md`
`references/javascript.md`
`references/php-cookies.md`
`references/php-forms.md`
`references/php-json.md`
`references/php-mysql-database.md`
`references/progressive-web-app.md`
`references/python-as-web-framework.md`
`references/python-contact-form.md`
`references/python-flask-app.md`
`references/python-flask.md`
`references/security.md`
`references/styling-web-forms.md`
`references/web-api.md`
`references/web-performance.md`
`references/xml.md` | | [excalidraw-diagram-generator](../skills/excalidraw-diagram-generator/SKILL.md) | Generate Excalidraw diagrams from natural language descriptions. Use when asked to "create a diagram", "make a flowchart", "visualize a process", "draw a system architecture", "create a mind map", or "generate an Excalidraw file". Supports flowcharts, relationship diagrams, mind maps, and system architecture diagrams. Outputs .excalidraw JSON files that can be opened directly in Excalidraw. | `references/element-types.md`
`references/excalidraw-schema.md`
`scripts/.gitignore`
`scripts/README.md`
`scripts/add-arrow.py`
`scripts/add-icon-to-diagram.py`
`scripts/split-excalidraw-library.py`
`templates/business-flow-swimlane-template.excalidraw`
`templates/class-diagram-template.excalidraw`
`templates/data-flow-diagram-template.excalidraw`
`templates/er-diagram-template.excalidraw`
`templates/flowchart-template.excalidraw`
`templates/mindmap-template.excalidraw`
`templates/relationship-template.excalidraw`
`templates/sequence-diagram-template.excalidraw` | | [gh-cli](../skills/gh-cli/SKILL.md) | GitHub CLI (gh) comprehensive reference for repositories, issues, pull requests, Actions, projects, releases, gists, codespaces, organizations, extensions, and all GitHub operations from the command line. | None | | [git-commit](../skills/git-commit/SKILL.md) | Execute git commit with conventional commit message analysis, intelligent staging, and message generation. Use when user asks to commit changes, create a git commit, or mentions "/commit". Supports: (1) Auto-detecting type and scope from changes, (2) Generating conventional commit messages from diff, (3) Interactive commit with optional type/scope/description overrides, (4) Intelligent file staging for logical grouping | None | diff --git a/skills/create-web-form/SKILL.md b/skills/create-web-form/SKILL.md new file mode 100644 index 000000000..7f6613648 --- /dev/null +++ b/skills/create-web-form/SKILL.md @@ -0,0 +1,85 @@ +--- +name: create-web-form +description: 'Create robust, accessible web forms with best practices for HTML structure, CSS styling, JavaScript interactivity, form validation, and server-side processing. Use when asked to "create a form", "build a web form", "add a contact form", "make a signup form", or when building any HTML form with data handling. Covers PHP and Python backends, MySQL database integration, REST APIs, XML data exchange, accessibility (ARIA), and progressive web apps.' +--- + +# Create Web Form Skill + +## Overview + +This skill provides comprehensive reference materials and best practices for creating web forms. It covers HTML syntax, UI/UX design, form validation, server-side processing (PHP and Python), data handling, and network communication. + +## Purpose + +Enable developers to build robust, accessible, and user-friendly web forms by providing: + +- HTML form syntax and structure +- CSS styling techniques for form elements +- JavaScript for form interactivity and validation +- Accessibility best practices +- Server-side form processing with PHP and Python +- Database integration methods +- Network data handling and security +- Performance optimization + +## Reference Files + +This skill includes the following reference documentation: + +### UI & Styling +- `styling-web-forms.md` - Form styling techniques and best practices +- `css-styling.md` - Comprehensive CSS reference for form styling + +### User Experience +- `accessibility.md` - Web accessibility guidelines for forms +- `javascript.md` - JavaScript techniques for form functionality +- `form-controls.md` - Native form controls and their usage +- `progressive-web-app.md` - Progressive web app integration + +### HTML Structure +- `form-basics.md` - Fundamental HTML form structure +- `aria-form-role.md` - ARIA roles for accessible forms +- `html-form-elements.md` - Complete HTML form elements reference +- `html-form-example.md` - Practical HTML form examples + +### Server-Side Processing +- `form-data-handling.md` - Network form data handling +- `php-forms.md` - PHP form processing +- `php-cookies.md` - Cookie management in PHP +- `php-json.md` - JSON handling in PHP +- `php-mysql-database.md` - Database integration with PHP +- `python-contact-form.md` - Python contact form implementation +- `python-flask.md` - Flask forms tutorial +- `python-flask-app.md` - Building Flask web applications +- `python-as-web-framework.md` - Python web framework basics + +### Data & Network +- `xml.md` - XML data format reference +- `hypertext-transfer-protocol.md` - HTTP protocol reference +- `security.md` - Web security best practices +- `web-api.md` - Web API integration +- `web-performance.md` - Performance optimization techniques + +## Usage + +When creating a web form, consult the appropriate reference files based on your needs: + +1. **Planning**: Review `form-basics.md` and `form-controls.md` +2. **Structure**: Use `html-form-elements.md` and `aria-form-role.md` +3. **Styling**: Reference `styling-web-forms.md` and `css-styling.md` +4. **Interactivity**: Apply techniques from `javascript.md` +5. **Accessibility**: Follow guidelines in `accessibility.md` +6. **Server Processing**: Choose between PHP or Python references +7. **Data Storage**: Consult database and data format references +8. **Optimization**: Review `web-performance.md` and `security.md` + +## Best Practices + +- Always validate input on both client and server sides +- Ensure forms are accessible to all users +- Use semantic HTML elements +- Implement proper error handling and user feedback +- Secure form data transmission with HTTPS +- Follow progressive enhancement principles +- Test forms across different browsers and devices +- Optimize for performance and user experience diff --git a/skills/create-web-form/references/accessibility.md b/skills/create-web-form/references/accessibility.md new file mode 100644 index 000000000..e12bb69fd --- /dev/null +++ b/skills/create-web-form/references/accessibility.md @@ -0,0 +1,512 @@ +# Web Accessibility Reference + +A consolidated reference guide drawn from MDN Web Docs covering core accessibility +concepts, authoring guidelines, safe browsing practices, ARIA-based widgets, and +mobile accessibility requirements. + +--- + +## 1. Accessibility Overview + +> **Source:** https://developer.mozilla.org/en-US/docs/Web/Accessibility + +### What Is Accessibility? + +**Accessibility** (abbreviated as **A11y** -- "a" + 11 characters + "y") in web +development means enabling as many people as possible to use websites, even when +those people's abilities are limited in some way. + +> "The Web is fundamentally designed to work for all people, whatever their +> hardware, software, language, location, or ability. When the Web meets this +> goal, it is accessible to people with a diverse range of hearing, movement, +> sight, and cognitive ability." -- W3C + +Key points: + +- Technology makes things **easier** for many people. +- Technology makes things **possible** for people with disabilities. +- Accessibility spans physical, cognitive, hearing, movement, and sight abilities. + +### Core Principles + +1. **Semantic HTML** -- Use correct elements for their intended purpose. +2. **Keyboard Navigation** -- Ensure full functionality without a mouse. +3. **Assistive Technology Support** -- Maintain compatibility with screen readers + and other tools. +4. **Perceivability** -- Content must be perceivable through multiple senses. +5. **Operability** -- All functionality must be keyboard accessible. +6. **Understandability** -- Clear language and predictable behavior. +7. **Robustness** -- Works across diverse assistive technologies. + +### Beginner Tutorial Modules (MDN Learn Web Development) + +| Module | Description | +|--------|-------------| +| What is Accessibility? | Groups to consider, tools users rely on, workflow integration | +| Accessibility Tooling and Assistive Technology | Tools for solving accessibility issues | +| HTML: A Good Basis for Accessibility | Semantic markup and correct element usage | +| CSS and JavaScript Best Practices | Accessible implementation of CSS and JS | +| WAI-ARIA Basics | Adding semantics for complex UI controls and dynamic content | +| Accessible Multimedia | Text alternatives for video, audio, and images | +| Mobile Accessibility | iOS/Android tools and mobile-specific considerations | + +### Key Standards and Frameworks + +- **WCAG (Web Content Accessibility Guidelines)** -- organized into Perceivable, + Operable, Understandable, and Robust categories. +- **ARIA (Accessible Rich Internet Applications)** -- 53+ attributes and 87+ + roles for adding semantic meaning to custom widgets. + +--- + +## 2. Information for Web Authors + +> **Source:** https://developer.mozilla.org/en-US/docs/Web/Accessibility/Guides/Information_for_Web_authors + +### Guidelines and Regulations + +#### ARIA Authoring Practices Guide (APG) + +- **Provider:** W3C +- **URL:** https://www.w3.org/WAI/ARIA/apg/ +- Design patterns and functional examples for accessible web experiences. +- Covers how to apply accessibility semantics to common design patterns and + widgets. + +#### Web Content Accessibility Guidelines (WCAG) + +- **Provider:** W3C Web Accessibility Initiative (WAI) +- **URL:** https://www.w3.org/WAI/standards-guidelines/wcag/ +- Important baseline guidelines being adopted by EU accessibility regulations. + +#### ARIA on MDN + +- Complete guides to ARIA roles, properties, and attributes. +- Best practices and code examples for each role. + +### How-to Guides + +| Guide | Provider | URL | +|-------|----------|-----| +| Accessibility for Teams | U.S. General Services Administration | https://digital.gov/guides/accessibility-for-teams/ | +| Accessible Web Page Authoring | IBM | https://www.ibm.com/able/requirements/requirements/ | + +### Automated Checking and Repair Tools + +#### Browser Extensions + +| Tool | URL | +|------|-----| +| HTML CodeSniffer | https://squizlabs.github.io/HTML_CodeSniffer/ | +| aXe DevTools | Built into browser DevTools | +| Lighthouse Accessibility Audit | Chrome DevTools integrated | +| Accessibility Insights | https://accessibilityinsights.io/ | +| WAVE | https://wave.webaim.org/extension/ | + +#### Build-Process / Programmatic Testing + +| Tool | Description | +|------|-------------| +| axe-core | Accessibility engine for automated testing (dequelabs/axe-core) | +| eslint-plugin-jsx-a11y | ESLint plugin for JSX accessibility rules | +| Lighthouse Audits | Programmable audit runner (GoogleChrome/lighthouse) | +| AccessLint.js | Automated a11y linting library | + +#### Continuous Integration + +- **AccessLint** (https://accesslint.com/) -- integrates with GitHub pull + requests for automated accessibility review. + +### Testing Recommendations + +Simulation and testing methods to employ: + +- Color blindness simulation +- Low vision simulation +- Low contrast testing +- Zoom testing +- Keyboard-only navigation (disable the mouse) +- Touch-only testing +- Voice command testing +- Testing with a **Web Disability Simulator** browser extension + +Best practice: **Test with real users whenever possible.** + +--- + +## 3. Browsing Safely + +> **Source:** https://developer.mozilla.org/en-US/docs/Web/Accessibility/Guides/Browsing_safely + +### Conditions Addressed + +| Condition | Common Triggers | +|-----------|-----------------| +| Vestibular Disorders | Motion, animations, parallax effects | +| Seizure Disorders | Flashing (3+ per second), flickering, high-contrast color changes | +| Photosensitivity | Color intensity, flashing, high contrast | +| Traumatic Brain Injury (TBI) | High cognitive load from color processing | + +### CSS Media Feature: `prefers-reduced-motion` + +Detects the user's OS-level preference for reduced motion. + +```css +@media (prefers-reduced-motion: reduce) { + * { + animation: none !important; + transition: none !important; + } +} +``` + +CSS transition events that developers can listen to: + +- `transitionrun` +- `transitionstart` +- `transitionend` +- `transitioncancel` + +### Platform-Level Browser Controls + +| Platform | Setting | Notes | +|----------|---------|-------| +| Safari Desktop (10.1+) | Disable Auto-Play | Does not affect animated GIFs | +| iOS Safari (10.3+) | Reduce Motion (OS Accessibility settings) | GIFs unaffected | +| Firefox | `image.animation_mode` set to `"none"` | Disables all animated GIFs | +| Reader Mode (various) | Content Blockers, text-to-speech, font/zoom | Reduces distractions | + +### Useful Browser Extensions + +| Extension | Purpose | Browser | +|-----------|---------|---------| +| Gif Blocker | Blocks all GIFs | Chrome | +| Gif Scrubber | Pause/play/scrub GIFs like a video | Chrome | +| Beeline Reader | Grayscale mode, dyslexia-friendly fonts, contrast | Chrome, Edge, Firefox | + +### Operating System Accessibility Features + +**Windows 10:** + +- Settings > Ease of Access > Display -- Turn off animations. +- Settings > Ease of Access > Display > Color Filters -- Toggle grayscale. +- Grayscale reduces cognitive load for TBI, photosensitive epilepsy, and other + conditions. + +**macOS:** + +- System Preferences > Accessibility > Display -- "Reduce motion" option. + +### WCAG Compliance: Success Criterion 2.3.1 + +**Three Flashes or Below Threshold** -- content must not flash more than three +times per second unless the flash is below the general flash and red flash +thresholds. + +### Best Practices for Developers + +**Do:** + +- Support the `prefers-reduced-motion` media query. +- Keep flashing below 3 times per second. +- Provide play/pause controls for all animations. +- Test with OS accessibility features enabled. + +**Do not:** + +- Auto-play videos or animations without user controls. +- Use high-frequency flashing or strobing effects. +- Assume all users can tolerate motion. + +### Implementation Checklist + +- [ ] Add `@media (prefers-reduced-motion: reduce)` rules to CSS. +- [ ] Disable auto-play animations when the user preference is set. +- [ ] Ensure GIFs have pause controls. +- [ ] Test in Windows and macOS accessibility modes. +- [ ] Validate against WCAG 2.3.1 (Three Flashes criterion). + +--- + +## 4. Accessible Web Applications and Widgets + +> **Source:** https://developer.mozilla.org/en-US/docs/Web/Accessibility/Guides/Accessible_web_applications_and_widgets + +### The Problem + +Custom JavaScript widgets (sliders, menu bars, tabs, dialogs) built with generic +HTML elements like `
` and `` lack semantic meaning for assistive +technologies. Dynamic content changes may not be detected by screen readers. + +### ARIA (Accessible Rich Internet Applications) + +ARIA fills the gap between standard HTML and desktop-style UI controls with three +types of attributes: + +1. **Roles** -- Describe widgets not natively available in HTML (sliders, menu + bars, tabs, dialogs). +2. **Properties** -- Describe characteristics (draggable, required, has popup). +3. **States** -- Describe current interaction state (busy, disabled, selected, + hidden). + +**Important:** Prefer semantic HTML elements over ARIA when available. ARIA is a +progressive enhancement for dynamic components. + +### Example: Tabs Widget + +**Without ARIA (non-accessible):** + +```html +
    +
  1. + Chapter 1 +
    2. +
  2. + Chapter 2 +
    3. +
+ +
+
Chapter 1 content goes here
+
Chapter 2 content goes here
+
+``` + +**With ARIA (accessible):** + +```html +
    + + +
+ +
+
+ Chapter 1 content goes here +
+
+ Chapter 2 content goes here +
+
+``` + +### Common ARIA State Attributes + +| Attribute | Purpose | +|-----------|---------| +| `aria-checked` | State of checkbox or radio button | +| `aria-disabled` | Visible but not editable/operable | +| `aria-grabbed` | "Grabbed" state in drag-and-drop | +| `aria-selected` | Selected state of an element | +| `aria-expanded` | Whether expandable content is open | +| `aria-pressed` | Pressed state of a toggle button | + +Use ARIA states to indicate UI state and CSS attribute selectors to style +accordingly. + +### Visibility Management with `aria-hidden` + +```html + +``` + +```css +div.tooltip[aria-hidden="true"] { + display: none; +} +``` + +```javascript +function showTip(el) { + el.setAttribute("aria-hidden", "false"); +} +``` + +### Role Changes + +Never change an element's ARIA role dynamically. Instead, replace the element +entirely: + +```javascript +// Correct: swap elements +// View mode +
Edit this text
+ +// Edit mode: replace with an input + +``` + +### Keyboard Navigation Best Practices + +| Key | Expected Behavior | +|-----|-------------------| +| Tab / Shift+Tab | Move focus into and out of the widget | +| Arrow Keys | Navigate between items within the widget | +| Enter / Spacebar | Activate the focused control | +| Escape | Close menus or dialogs | +| Home / End | Jump to first or last item | + +Focus management considerations: + +- Maintain focus order that matches visual layout. +- Use `tabindex="0"` to make custom elements keyboard accessible. +- Avoid `tabindex > 0` (breaks natural tab order). +- Update the visual focus indicator for keyboard users. +- Move focus programmatically when opening dialogs or modals. + +### Key ARIA Attributes for Interactive Widgets + +**Labeling and Description:** + +| Attribute | Usage | +|-----------|-------| +| `aria-label` | Direct text label | +| `aria-labelledby` | References the element that labels this one | +| `aria-describedby` | References additional descriptive text | +| `aria-description` | Inline description text | + +**Relationships:** + +| Attribute | Usage | +|-----------|-------| +| `aria-controls` | This element controls another element | +| `aria-owns` | Establishes parent-child relationships | +| `aria-flowto` | Defines logical reading order | + +**Widget Behavior:** + +| Attribute | Usage | +|-----------|-------| +| `aria-haspopup` | Has a popup (menu, listbox, dialog, grid, tree) | +| `aria-expanded` | Expandable content state (true/false) | +| `aria-modal` | Modal dialog (true) | +| `aria-live` | Live region announcements (polite, assertive, off) | +| `aria-busy` | Loading or processing state (true/false) | + +### Live Regions for Dynamic Content + +```html +
+ Updates will be announced to screen readers +
+``` + +- `aria-live="polite"` -- announce when convenient. +- `aria-live="assertive"` -- announce immediately. +- `aria-atomic="true"` -- announce the entire region, not just the changed part. + +--- + +## 5. Mobile Accessibility Checklist + +> **Source:** https://developer.mozilla.org/en-US/docs/Web/Accessibility/Guides/Mobile_accessibility_checklist + +A checklist of accessibility requirements for mobile app developers targeting +WCAG 2.2 AA compliance. + +### Color + +- **Normal text:** minimum 4.5:1 contrast ratio (less than 18pt or 14pt bold). +- **Large text:** minimum 3:1 contrast ratio (at least 18pt or 14pt bold). +- Information conveyed via color must also be available through other means (e.g., + underlines for links). + +### Visibility + +- Do NOT hide content exclusively with zero opacity, z-index ordering, or + off-screen placement. +- Use the `hidden` HTML attribute, `visibility`, or `display` CSS properties to + truly hide content. +- Avoid `aria-hidden` unless absolutely necessary. +- Critical for single-page apps where multiple views/cards may overlap. + +### Focus + +- Standard controls (links, buttons, form fields) are focusable by default. +- Custom controls must have an appropriate ARIA Role (e.g., `button`, `link`, + `checkbox`). +- Focus order must be logical and consistent. + +### Text Equivalents + +- Provide text alternatives for all non-text elements using `alt`, `title`, + `aria-label`, `aria-labelledby`, or `aria-describedby`. +- Avoid images of text. +- Visible UI component text must match the programmatic name (WCAG 2.1: Label in + Name). +- All form controls must have associated `