jekyll-bootstrap-accessibility

name	jekyll-bootstrap-accessibility
description	Create accessible and efficient websites using Jekyll and Bootstrap. Use for planning, building, and reviewing static sites with semantic HTML, WCAG-aware UX, fast performance, and maintainable templates.
argument-hint	What site/page are you building, and what constraints matter most?

Jekyll + Bootstrap Accessible Website Workflow

What This Skill Produces

• A repeatable process to build or refactor a Jekyll site that is accessible, performant, and maintainable.
• A concrete definition of done for structure, navigation, content, and performance.
• Consistent implementation choices for layouts, components, and assets.

When to Use

• Starting a new Jekyll website with Bootstrap.
• Refactoring an existing Jekyll site for accessibility and speed.
• Reviewing pull requests that change templates, navigation, forms, or media.
• Preparing a site for handoff to non-technical editors.

Required Inputs

• Site goal and primary audience.
• Content inventory (pages, posts, media, downloadable files).
• Constraints: hosting, browser support, expected traffic, deadlines.

Default Assumptions

• Jekyll: current stable version.
• Bootstrap: 5.x.
• Accessibility target: WCAG 2.2 AA.
• Performance budget for typical content pages: transfer size <= 500KB, JavaScript <= 120KB.

Workflow

1. Define outcomes and non-negotiables.
2. Plan information architecture and template strategy.
3. Implement semantic, accessible base templates in Jekyll.
4. Add Bootstrap components with accessible usage patterns.
5. Optimize assets and runtime performance.
6. Validate accessibility, responsiveness, and regressions.
7. Finalize editor guidance and maintenance checks.

Detailed Procedure

1) Define outcomes and non-negotiables

• Identify top tasks users must complete on the site.
• Set quality bars before coding:
  • Accessibility (WCAG 2.2 AA): keyboard support, visible focus, sufficient color contrast, meaningful labels, alt text.
  • Performance: pages should remain lightweight; avoid unnecessary scripts and oversized media.
  • Maintainability: content changes should happen in Markdown/data files, not repeated HTML edits.

Completion checks:

• Success criteria are written and testable.
• Scope includes required page types (home, content, listing, detail, contact if needed).
• Explicit acceptance criteria include WCAG 2.2 AA checks for key workflows.

2) Plan information architecture and template strategy

• Define collections, front matter fields, and reusable layout hierarchy:
  • _layouts/default.html for base shell.
  • Section-specific layouts for page types.
  • _includes/ for shared components (header, nav, footer, alerts, cards).
• Decide navigation depth and URL structure.

Decision points:

• If many similar pages share structure, create/include a reusable partial.
• If editors need repeated structured blocks, model them in front matter or _data.

Completion checks:

• Every page type maps to a layout.
• Repeated UI patterns are documented as includes, not duplicated markup.

3) Implement semantic, accessible base templates in Jekyll

• Use landmarks and heading hierarchy (header, nav, main, aside, footer; one h1 per page).
• Add skip link targeting main content.
• Ensure nav, search, and forms are keyboard usable with clear focus styling.
• Use descriptive link text and explicit form labels.

Decision points:

• If visual text is ambiguous, expand accessible name with hidden helper text.
• If a decorative image adds no meaning, use empty alt text.

Completion checks:

• Keyboard-only navigation works end-to-end.
• Focus order matches visual reading order.
• All controls have accessible names.

4) Add Bootstrap components with accessible usage patterns

• Prefer Bootstrap components that preserve native semantics.
• Keep interactive controls as buttons/links rather than generic div elements.
• For collapse, dropdown, modal, and tabs:
  • Verify ARIA attributes are present and state changes are synchronized.
  • Verify focus management (open, close, and return focus behavior).
• Keep customization in a small, intentional CSS layer; avoid overriding component behavior blindly.

Decision points:

• If component customization requires heavy override chains, replace with simpler markup.
• If JavaScript is optional, implement progressive enhancement so core content still works.

Completion checks:

• Components remain usable without a mouse.
• Customized styles keep contrast and focus visibility.

5) Optimize assets and runtime performance

• Use responsive images and modern formats where possible; avoid shipping oversized originals.
• Minimize script usage and defer non-critical JavaScript.
• Reduce CSS payload by importing only needed Bootstrap parts when build pipeline allows.
• Avoid layout shift: reserve media dimensions and stabilize above-the-fold structure.

Decision points:

• If a feature adds significant JS/CSS for minor value, prefer simpler static alternatives.
• If third-party embeds are needed, lazy-load or gate behind user action.

Completion checks:

• No obvious render-blocking bottlenecks.
• Largest pages stay within budget (<= 500KB transfer, <= 120KB JavaScript) unless explicitly exempted.

6) Validate accessibility, responsiveness, and regressions

• Test at mobile, tablet, and desktop breakpoints.
• Test keyboard navigation and visible focus on all key workflows.
• Test screen reader announcements for nav, forms, and dynamic components.
• Run automated checks (lint/a11y/perf) and manually verify failures.

Completion checks:

• Critical accessibility issues are resolved or explicitly tracked.
• No layout breakage across supported viewport ranges.

7) Finalize editor guidance and maintenance checks

• Document how non-technical editors add/update pages and media.
• Provide content patterns for headings, links, alt text, and tables.
• Add a lightweight release checklist for accessibility and performance regression checks.

Completion checks:

• Editing workflow is documented.
• Team can repeat quality checks before publishing.

Definition Of Done

• Templates are semantic and keyboard accessible.
• Bootstrap components are used with accessible interaction behavior.
• Content is manageable through Jekyll front matter/collections/data.
• Performance bottlenecks are addressed and monitored.
• A repeatable release checklist exists for future updates.