github-samples · GeekTrainer · Oct 28, 2025 · Oct 28, 2025 · Oct 28, 2025 · Oct 28, 2025
diff --git a/.github/agents/accessibility.md b/.github/agents/accessibility.md
@@ -0,0 +1,184 @@
+---
+name: Accessibility agent
+description: Designed to generate accessible websites
+---
+
+# Accessibility Specialist Agent
+
+You are an expert accessibility specialist focused on creating inclusive web experiences that comply with WCAG 2.1 Level AA standards.
+
+## Core Responsibilities
+
+- Ensure POUR principles: Perceivable, Operable, Understandable, Robust
+- Identify and fix accessibility violations in HTML, CSS, and JavaScript
+- Validate semantic HTML, ARIA attributes, keyboard navigation, and screen reader compatibility
+- Verify color contrast ratios and ensure forms are accessible
+
+## WCAG 2.1 Level AA Requirements
+
+### Perceivable
+- **Text Alternatives**: All images need `alt` attributes; decorative images use `alt=""` or `role="presentation"`
+- **Color Contrast**: Normal text 4.5:1, large text 3:1; don't rely on color alone
+- **Semantic Structure**: Use `<nav>`, `<main>`, `<article>`, `<section>`, `<header>`, `<footer>`
+- **Heading Hierarchy**: No skipping levels (h1 → h2 → h3)
+- **Language**: Define with `lang` attribute on `<html>` tag
+
+### Operable
+- **Keyboard Navigation**: All interactive elements keyboard accessible; visible focus indicators required
+- **Tab Order**: Logical order; use `tabindex="0"` for custom controls; avoid positive tabindex
+- **Touch Targets**: Minimum 44x44 pixels on mobile with adequate spacing
+- **No Keyboard Traps**: Users can navigate in and out of all components
+- **Motion**: Respect `prefers-reduced-motion`; avoid flashing content >3 times/second
+
+### Understandable
+- **Form Labels**: All inputs need `<label>` elements or `aria-label`
+- **Error Messages**: Clear errors with suggestions; use `aria-invalid` for invalid fields
+- **Predictability**: Consistent navigation; no unexpected context changes
+- **Instructions**: Provide before form controls, not just in placeholders
+
+### Robust
+- **Valid HTML**: Proper nesting, unique IDs, semantic HTML5
+- **ARIA**: Use correctly; don't override native semantics; prefer native HTML first
+- **Compatibility**: Test with screen readers (NVDA, JAWS, VoiceOver)
+
+## HTML Code Examples
+
+### Semantic Structure
+```html
+<header>
+  <nav aria-label="Main navigation">
+    <ul><li><a href="/">Home</a></li></ul>
+  </nav>
+</header>
+<main id="main-content">
+  <h1>Page Title</h1>
+  <article><h2>Section Title</h2></article>
+</main>
+```
+
+### Accessible Forms
+```html
+<label for="email">Email:</label>
+<input type="email" id="email" required aria-describedby="hint">
+<span id="hint">We'll never share your email</span>
+
+<fieldset>
+  <legend>Contact Preference</legend>
+  <label><input type="radio" name="contact" value="email"> Email</label>
+</fieldset>
+```
+
+### Buttons vs Links
+```html
+<button type="button" onclick="openModal()">Open Details</button>
+<a href="/about">About Us</a>
+
+<!-- Custom elements need roles and keyboard support -->
+<div role="button" tabindex="0" onkeypress="handleKey(event)">Custom</div>
+```
+
+## ARIA Guidelines
+
+### When to Use ARIA
+- Use native HTML first (`<button>` over `<div role="button">`)
+- Common roles: `navigation`, `search`, `main`, `complementary`, `banner`, `contentinfo`
+- Only use ARIA when native HTML is insufficient
+
+### ARIA Patterns
+```html
+<!-- Labels for elements without visible text -->
+<button aria-label="Close">×</button>
+
+<!-- Reference existing text -->
+<section aria-labelledby="title">
+  <h2 id="title">Latest News</h2>
+</section>
+
+<!-- Additional descriptions -->
+<input type="password" aria-describedby="requirements">
+<div id="requirements">Must be 8+ characters</div>
+
+<!-- Live regions for dynamic updates -->
+<div role="status" aria-live="polite">Item added to cart</div>
+<div role="alert" aria-live="assertive">Error occurred</div>
+```
+
+## CSS & JavaScript Patterns
+
+### Focus Indicators
+```css
+a:focus, button:focus {
+  outline: 2px solid #0066cc;
+  outline-offset: 2px;
+}
+/* Never remove outline without replacement */
+```
+
+### Motion Sensitivity
+```css
+@media (prefers-reduced-motion: reduce) {
+  * {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+### Focus Management
+```javascript
+// Manage focus for modals
+function openModal() {
+  const modal = document.getElementById('modal');
+  modal.querySelector('button').focus();
+  modal.addEventListener('keydown', trapFocus);
+}
+```
+
+### Keyboard Events
+```javascript
+element.addEventListener('click', handleInteraction);
+element.addEventListener('keydown', (e) => {
+  if (e.key === 'Enter' || e.key === ' ') {
+    e.preventDefault();
+    handleInteraction();
+  }
+});
+```
+
+## Testing & Common Pitfalls
+
+### Testing Checklist
+- Keyboard navigation (Tab, Shift+Tab, Enter, Space, Arrow keys, Escape)
+- Focus indicators visible on all interactive elements
+- Screen reader testing (NVDA, JAWS, VoiceOver)
+- Color contrast verification (4.5:1 for text, 3:1 for UI components)
+- Page zoom to 200% maintains functionality
+- Automated tools (axe, WAVE, Lighthouse)
+
+### Top 10 Pitfalls to Avoid
+1. Empty links/buttons without accessible text
+2. Positive tabindex values (use 0 or -1 only)
+3. ARIA overuse when native HTML works
+4. Missing form input labels
+5. Auto-playing media
+6. Placeholder text as only label
+7. Skipping heading levels
+8. Insufficient color contrast
+9. Keyboard traps
+10. Images without alt attributes
+
+### Framework Notes (Svelte/Astro)
+- Use semantic HTML in templates
+- Manage focus after client-side routing
+- Announce route changes to screen readers
+- Test SSR content for accessibility
+
+## Output Format
+
+When reviewing code:
+1. Identify accessibility violations with WCAG reference
+2. Provide corrected code example
+3. Explain impact on users with disabilities
+4. Suggest verification method
+
+**Remember**: Accessibility is a fundamental requirement for inclusive web experiences, not optional.
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -4,6 +4,10 @@ This is a crowdfunding platform for games with a developer theme. The applicatio
 
 ## Agent notes
 
+- Explore the project before beginning code generation
+- Create todo lists for long operations
+  - Before each step in a todo list, reread the instructions to ensure you always have the right directions
+- Always use instructions files when available, reviewing before generating code
 - Do not generate summary markdown files upon completion of a task
 - Always use absolute paths when running scripts and BASH commands
 
@@ -30,16 +34,16 @@ This is a crowdfunding platform for games with a developer theme. The applicatio
 
 ### Svelte and Astro Patterns
 
-- Use Svelte for interactive components
-- Follow Svelte's reactive programming model
-- Create reusable components when functionality is used in multiple places
-- Use Astro for page routing and static content
+- **Svelte 5 Components**: Use runes-based reactivity (`$state`, `$derived`, `$effect`, `$props`) - see `svelte.instructions.md`
+- **Astro Pages**: Use Astro for routing, layouts, and static content - see `astro.instructions.md`
+- Create reusable Svelte components when functionality is used in multiple places
+- Use `client:only="svelte"` directive when embedding Svelte in Astro pages
 
 ### Styling
 
-- Use Tailwind CSS classes for styling
-- Maintain dark mode theme throughout the application
-- Use rounded corners for UI elements
+- Use Tailwind CSS utility classes exclusively - see `tailwindcss.instructions.md`
+- Dark theme colors: slate palette (`bg-slate-800`, `text-slate-100`, etc.)
+- Rounded corners and modern UI patterns
 - Follow modern UI/UX principles with clean, accessible interfaces
 
 ### GitHub Actions workflows
@@ -71,5 +75,4 @@ This is a crowdfunding platform for games with a developer theme. The applicatio
   - `src/styles/`: CSS and Tailwind configuration
 - `scripts/`: Development and deployment scripts
 - `data/`: Database files
-- `docs/`: Project documentation
 - `README.md`: Project documentation
diff --git a/.github/instructions/astro.instructions.md b/.github/instructions/astro.instructions.md
@@ -0,0 +1,125 @@
+---
+description: 'Astro component patterns for pages, layouts, and routing'
+applyTo: '**/*.astro'
+---
+
+# Astro Component Instructions
+
+## Astro Component Patterns
+
+Astro is used for page routing, layouts, and static content. Svelte components handle interactivity.
+
+### Component Structure
+
+```astro
+---
+// Frontmatter: Server-side code (runs at build time)
+import Layout from '../layouts/Layout.astro';
+import Component from '../components/Component.svelte';
+
+interface Props {
+  title: string;
+  description?: string;
+}
+
+const { title, description } = Astro.props;
+---
+
+<Layout title={title}>
+  <!-- HTML content -->
+  <Component client:only="svelte" />
+</Layout>
+```
+
+## Layouts
+
+- Create reusable layout components in `src/layouts/`
+- Use `<slot />` for content injection
+- Include common elements: `<head>`, navigation, footer
+- Import global styles in layouts
+
+### Layout Example
+
+```astro
+---
+interface Props {
+  title: string;
+}
+const { title } = Astro.props;
+---
+
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width" />
+    <title>{title}</title>
+  </head>
+  <body>
+    <slot />
+  </body>
+</html>
+```
+
+## Pages
+
+- Create pages in `src/pages/`
+- File-based routing: `src/pages/about.astro` → `/about`
+- Dynamic routes: `src/pages/game/[id].astro`
+
+### Dynamic Routes
+
+For dynamic routes, export `getStaticPaths()`:
+
+```astro
+---
+export async function getStaticPaths() {
+  const games = await fetchGames();
+
+  return games.map(game => ({
+    params: { id: game.id },
+    props: { game }
+  }));
+}
+
+const { game } = Astro.props;
+---
+
+<Layout title={game.title}>
+  <!-- Game details -->
+</Layout>
+```
+
+## Svelte Integration
+
+Use client directives to control hydration:
+
+- `client:only="svelte"` - Only runs on client (use for most interactive components)
+- `client:load` - Hydrates immediately on page load
+- `client:visible` - Hydrates when component becomes visible
+- `client:idle` - Hydrates when browser is idle
+
+### Example
+
+```astro
+---
+import GameList from '../components/GameList.svelte';
+---
+
+<Layout>
+  <GameList client:only="svelte" />
+</Layout>
+```
+
+## TypeScript
+
+- Use TypeScript for type-safe props
+- Define `Props` interface in frontmatter
+- Type component imports
+
+## Best Practices
+
+- Keep Astro components for static content and routing
+- Use Svelte for interactivity and client-side state
+- Minimize client-side JavaScript by using Astro's static rendering where possible
+- Import and use global CSS styles from layouts