https://github.com/evanminto/html-annex

Accessible, progressively enhanced, minimally styled Web Components for common design patterns
https://github.com/evanminto/html-annex

Last synced: 6 days ago
JSON representation

Accessible, progressively enhanced, minimally styled Web Components for common design patterns

• Host: GitHub
• URL: https://github.com/evanminto/html-annex
• Owner: evanminto
• Created: 2019-05-28T01:49:00.000Z (over 5 years ago)
• Default Branch: master
• Last Pushed: 2022-12-03T11:49:55.000Z (almost 2 years ago)
• Last Synced: 2023-05-31T01:24:03.200Z (over 1 year ago)
• Language: JavaScript
• Homepage:
• Size: 52.7 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 3
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# HTML Annex

HTML Annex is a collection of Web Components for common UI design patterns,

implemented according to strict principles of accessibility and progressive

enhancement. Components are small and minimally styled to make them as easy as

possible to integrate into a variety of projects.

If built-in HTML elements are the house, HTML Annex is the annex built alongside

it, extending it with additional functionality not covered in the original design.

**NOTE:** This project is currently a work-in-progress and is not yet suitable

for production use.

## Documentation

Coming soon! I’ll probably put it on a separate site so I can document usage for

each component on its own page.

## Principles

All components are built with the following principles in mind:

* **Progressive enhancement:** Web user experiences experiences should be usable even when JavaScript doesn’t

  load.

* **Inclusion:** Users should be able to access equivalent experiences

  regardless of their disability, social or economic status, or identity. All

  components should meet WCAG AAA criteria.

* **Performance:** Components should respect users’ time and bandwidth limitations by

  delivering maximum utility with minimal file size.

* **Options**: Components should have options for customizing behavior, and it

  should be easy to style them to match the elements around them.

* **Platform consistency:** Whenever possible, components’ behaviors and APIs

  should be consistent with their equivalents for built-in elements and APIs.

## Questions You Were About to Ask

### Is this a design system?

Nope. HTML Annex is intended as a toolkit for people building websites, web

apps, and design systems. It features minimal styling intended to match user

agent styles as much as possible, so you are free to customize components for your own use cases.

### Will these components work with my React/Vue/Angular project?

Yes! The components are built using Web Components, a set of relatively new Web

platform standards (including Custom Elements and Shadow DOM) that are supported

in Chrome, Safari, Firefox, Samsung Internet, Opera, and more. Because these

standards are built into the browser, Web Components should work with all major

frameworks. They’re basically just like regular HTML elements!

### What about server rendering?

A common complaint about Web Components is that there isn’t a built-in solution

for rendering their contents on the server for purposes of SEO and performance.

But pre-rendering the Shadow DOM on the server is only one possible option. The

other approach, which HTML Annex uses, is to build fallback HTML on the server

and deliver that. The fallback content is usable immediately, and once the

JavaScript loads, the Web Components can replace it with the full experience.

This has the added benefit of making components usable in situations where

rendering JavaScript framework code on the server is impractical, such as some

legacy PHP setups.