Skip to content

Latest commit

 

History

History
122 lines (87 loc) · 4.5 KB

README.md

File metadata and controls

122 lines (87 loc) · 4.5 KB

Toolbelt

Netlify Status Built with Starlight

Toolbelt is a headless and unstyled component library for common accessibility patterns, built on top of Alpine.js. The library is tech-agnostic. As long as you're producing HTML, Toolbelt is compatible.

Upstatement builds websites for various brands and with various technologies but accessibility conformance is a constant across our work. Toolbelt is meant to bridge the knowledge gap in our web accessibility practice by providing components that adhere to WCAG and WAI-ARIA patterns out of the box, regardless of the technology stack we use.

Installation

There are two ways to install Toolbelt. In either case, it might be helpful to read through how installation works for Alpine core. The following guide skips some details that are already covered in Alpine’s documentation.

From a script tag

The easiest way to install Toolbelt is to include its CDN link. Because Toobelt is an Alpine plugin, you will have to include Alpine as a dependency. In addition, the Focus plugin is a required dependency for Toolbelt. Notice that Toolbelt and Alpine plugins come before Alpine core.

Include the following script tags in your <head>:

<head>
  <!-- Toolbelt -->
  <script
    src="https://cdn.jsdelivr.net/npm/@upstatement/[email protected]/dist/plugin.cdn.js"
    defer
  ></script>

  <!-- Focus plugin (Toolbelt dependency) -->
  <script
    src="https://cdn.jsdelivr.net/npm/@alpinejs/[email protected]/dist/cdn.min.js"
    defer
  ></script>

  <!-- Alpine core -->
  <script
    src="https://cdn.jsdelivr.net/npm/[email protected]/dist/cdn.min.js"
    defer
  ></script>
</head>

As a module

If you prefer bundling Toolbelt and its dependencies in your own Javascript bundle, you can install these packages from the npm registry.

  1. Install the following packages:

     npm install alpinejs @alpinejs/focus @upstatement/toolbelt

  2. Import and initialize the packages like so:

    import Alpine from "alpinejs";
import focus from "@alpinejs/focus";
import toolbelt from "@upstatement/toolbelt";

window.Alpine = Alpine;

Alpine.plugin(toolbelt);
Alpine.plugin(focus);

Alpine.start();

Contributing

Repository Structure

This repository hosts the Astro Starlight documentation site and library files for Toolbelt.

toolbelt
├── public                # (Astro) Asset files
├── scripts               # (Toolbelt) Build scripts
├── src
│   ├── components        # (Astro) Components
│   ├── content           # (Astro) Markdown documentation files
│   └── lib               # (Toolbelt) Library files
│       ├── __tests__     # (Toolbelt) Test suites
│       ├── builds        # (Toolbelt) Build files (e.g. CDN, ESM)
│       └── toolbelt      # (Toolbelt) Components
├── tailwind.config.mjs   # (Astro) Tailwind configuration
└── vitest.config.js      # (Toolbelt) Vitest configuration

Getting Started

  1. Install and use specified Node version.
nvm use
  1. Install repository dependencies.
npm install
  1. If you're working on the Astro site, start the local dev server. You can view the website at localhost:3000
npm run dev
  1. If you're working on Toolbelt, start the tests on watch mode. This is to encourage test-driven development (TDD).
npm run test:watch

Commands

Command Action
npm install Installs dependencies
npm run dev Starts local dev server at localhost:3000
npm run build Build the production site to ./dist/
npm run test Run tests
npm run test:watch Run tests on watch mode
npm run package:build Build the production packages