@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/rules/typescript.md

@@ -0,0 +1,52 @@
+---
+name: typescript
+description: Code style and best practice rules for TypeScript.
+globs:
+  - "**/*.ts"
+  - "**/*.tsx"
+---
+
+# TypeScript Rules
+
+## Style
+- Enable `strict: true` in every tsconfig; never weaken with `skipLibCheck` in application code
+- Use `PascalCase` for types, interfaces, enums, and classes; `camelCase` for variables and functions; `UPPER_SNAKE_CASE` for constants
+- Prefix interfaces only when distinguishing from a class of the same name; prefer no `I` prefix
+- One exported declaration per file for major types; co-locate small helper types in the same file
+- Use barrel exports (`index.ts`) per module boundary, not per directory
+- Keep import order: node builtins, external packages, internal packages, relative imports, separated by blank lines
+- Limit files to a single responsibility; split when a file exceeds 300 lines
+- Use explicit return types on exported functions; inferred types are acceptable for internal helpers
+- Prefer `type` over `interface` unless declaration merging is needed
+- Group related type definitions at the top of the file, before runtime code
+
+## Patterns
+- Use `unknown` instead of `any` for values of uncertain type; narrow with type guards before use
+- Use discriminated unions with exhaustive `switch` statements; add a `default: never` check to catch unhandled cases
+- Prefer branded types (`type UserId = string & { __brand: 'UserId' }`) for domain identifiers to prevent accidental mixing
+- Use `readonly` arrays and properties by default; mutate only when performance requires it
+- Handle errors with typed Result patterns (`{ ok: true; value: T } | { ok: false; error: E }`) instead of thrown exceptions for expected failures
+- Use `async/await` over raw Promises; never mix `.then()` chains with `await` in the same function
+- Prefer `Map` and `Set` over plain objects when keys are dynamic or non-string
+- Use `satisfies` operator to validate object shapes without widening the inferred type
+- Use template literal types for string patterns that follow a known format
+- Prefer `const` assertions (`as const`) for literal tuples and fixed configuration objects
+- Use `Zod` or similar runtime validators at system boundaries; never trust external input matches your types
+
+## Avoid
+- Never use `any`; use `unknown` and narrow, or define a proper type
+- Never use `@ts-ignore`; use `@ts-expect-error` with a comment explaining why
+- Never use `enum` with computed values; prefer `const` objects with `as const` or string literal unions
+- Never reassign function parameters; create a new variable instead
+- Never use `delete` operator on objects; restructure with spread or create a new object
+- Never use non-null assertion (`!`) unless you can prove the value exists in the same scope
+- Never export mutable state; export functions that return or modify encapsulated state
+- Never use `Function` type; spell out the full signature `(arg: Type) => ReturnType`
+
+## Testing
+- Use `describe`/`it` blocks with descriptive names: `it('returns 404 when user does not exist')`
+- Test the public API of each module; avoid testing private internals directly
+- Use factory functions to build test fixtures; avoid shared mutable state between tests
+- Assert specific values, not just truthiness; prefer `toEqual` over `toBeTruthy`
+- Mock external dependencies at the boundary (HTTP, DB, filesystem); never mock the module under test
+- Aim for one assertion per test; split multi-assert tests into separate `it` blocks when they test different behaviors

package/assets/rules/yaml-json.md

@@ -0,0 +1,51 @@
+---
+name: yaml-json
+description: Code style and best practice rules for YAML and JSON configuration files.
+globs:
+  - "**/*.yml"
+  - "**/*.yaml"
+  - "**/*.json"
+---
+
+# YAML & JSON Rules
+
+## Style
+- Use 2-space indentation in YAML; never use tabs
+- Use 2-space indentation in JSON for human-readable files; use minified JSON only for API responses and build artifacts
+- Use `snake_case` for keys in configuration files; use `camelCase` only when matching a language SDK convention (e.g., `tsconfig.json`)
+- Keep file names lowercase with hyphens: `docker-compose.yml`, `app-config.yaml`
+- Use `.yml` extension consistently within a project; do not mix `.yml` and `.yaml`
+- Place the most important or required keys at the top of each object; group related keys together
+- Use blank lines to separate logical sections in YAML; add `# comment` headers above each section
+- Wrap long strings in YAML with `>-` (folded, no trailing newline) or `|-` (literal, no trailing newline)
+- Use explicit `true`/`false` in YAML for booleans; never rely on `yes`/`no`/`on`/`off` implicit conversions
+- Keep JSON files under 500 lines; split large configurations into multiple files with `$ref` or tool-specific includes
+
+## Patterns
+- Use YAML anchors (`&anchor`) and aliases (`*anchor`) to eliminate duplication in repeated configuration blocks
+- Use `<<: *anchor` merge key to inherit and override properties from a base configuration
+- Define a JSON Schema or YAML schema for every configuration file; validate in CI with `ajv` or `yamllint`
+- Use environment variable interpolation (`${VAR}` or `!env VAR`) where supported by the tool, instead of hardcoded values
+- Use multi-document YAML (`---` separator) only when the consuming tool requires it (e.g., Kubernetes manifests)
+- Use JSON with comments (`jsonc`) for configuration files that benefit from inline documentation (e.g., `tsconfig.json`, `.vscode/settings.json`)
+- Use arrays for ordered collections and objects for named key-value pairs; never use an object when order matters
+- Use `null` explicitly in JSON for absent values; in YAML use `~` or omit the key entirely depending on schema requirements
+- Pin versions in dependency files to exact versions or narrow ranges; never use `latest` or `*`
+- Use `$schema` property in JSON files to enable IDE validation and autocompletion where supported
+- Prefer flat structures over deeply nested objects; limit nesting to 4 levels maximum
+
+## Avoid
+- Never use duplicate keys in the same object; most parsers silently use the last value, hiding bugs
+- Never store secrets, API keys, or passwords in YAML or JSON files; use environment variables or a secrets manager
+- Never use YAML implicit typing that converts strings to unexpected types: quote `"yes"`, `"no"`, `"on"`, `"off"`, `"null"`, `"true"`, `"false"` when they are string values
+- Never use YAML flow style (`{key: value}`) for objects with more than 3 keys; use block style for readability
+- Never commit `package-lock.json` or `yarn.lock` changes that are unrelated to the current PR
+- Never use trailing commas in JSON; they are invalid per the JSON spec
+- Never leave commented-out configuration blocks in committed files; remove or use a feature flag
+
+## Testing
+- Validate YAML files with `yamllint` using a shared `.yamllint.yml` config; enforce consistent quoting and indentation
+- Validate JSON files with `jsonlint` or `ajv validate` against the declared schema
+- Test configuration loading in application unit tests; verify that missing required keys produce clear error messages
+- Use snapshot tests for generated configuration files to detect unintended changes
+- Verify that environment variable placeholders resolve correctly in staging before deploying to production

package/assets/skills/accessibility.md

@@ -0,0 +1,210 @@
+---
+name: accessibility
+description: Accessibility patterns with ARIA, keyboard navigation, screen readers, color contrast, and focus management.
+---
+
+# Web Accessibility
+
+## When to Use
+Apply to every web interface you build. Accessibility is not a feature -- it is a baseline requirement. Over 15% of users have some form of disability. Accessible sites rank better in SEO, work on more devices, and avoid legal liability under ADA and EAA.
+
+## How It Works
+
+### Semantic HTML First
+
+Use the right element before reaching for ARIA. Native elements provide keyboard handling, focus management, and screen reader announcements for free.
+
+```html
+<!-- BAD -- div soup requires manual keyboard/ARIA work -->
+<div class="btn" onclick="submit()">Submit</div>
+<div class="input-wrapper"><div contenteditable="true"></div></div>
+<div class="nav"><div class="link" onclick="go('/about')">About</div></div>
+
+<!-- GOOD -- native elements handle accessibility automatically -->
+<button type="submit">Submit</button>
+<input type="text" aria-label="Search" />
+<nav><a href="/about">About</a></nav>
+```
+
+Semantic elements: `<button>`, `<a>`, `<input>`, `<select>`, `<nav>`, `<main>`, `<header>`, `<footer>`, `<article>`, `<section>`, `<dialog>`, `<details>`, `<table>`, `<form>`, `<label>`, `<fieldset>`, `<legend>`.
+
+### ARIA -- When HTML Is Not Enough
+
+Use ARIA to fill gaps that semantic HTML cannot cover:
+
+```tsx
+// Tabs -- no native HTML element for tab interfaces
+<div role="tablist" aria-label="Account settings">
+  <button
+    role="tab"
+    aria-selected={activeTab === "profile"}
+    aria-controls="panel-profile"
+    id="tab-profile"
+    onClick={() => setTab("profile")}
+  >
+    Profile
+  </button>
+  <button
+    role="tab"
+    aria-selected={activeTab === "security"}
+    aria-controls="panel-security"
+    id="tab-security"
+    onClick={() => setTab("security")}
+  >
+    Security
+  </button>
+</div>
+<div
+  role="tabpanel"
+  id="panel-profile"
+  aria-labelledby="tab-profile"
+  hidden={activeTab !== "profile"}
+>
+  {/* profile content */}
+</div>
+
+// Live regions -- announce dynamic content to screen readers
+<div aria-live="polite" aria-atomic="true">
+  {notification && <p>{notification}</p>}
+</div>
+
+// Loading states
+<button aria-busy={isLoading} disabled={isLoading}>
+  {isLoading ? "Saving..." : "Save"}
+</button>
+```
+
+### Keyboard Navigation
+
+Every interactive element must be operable with keyboard alone:
+
+```tsx
+function Modal({ isOpen, onClose, children }: ModalProps) {
+  const modalRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    const focusable = modalRef.current?.querySelectorAll<HTMLElement>(
+      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+    );
+    if (!focusable?.length) return;
+
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+    first.focus();
+
+    function handleKeyDown(e: KeyboardEvent) {
+      if (e.key === "Escape") { onClose(); return; }
+      if (e.key !== "Tab") return;
+      if (e.shiftKey && document.activeElement === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    }
+
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [isOpen, onClose]);
+
+  if (!isOpen) return null;
+  return (
+    <div ref={modalRef} role="dialog" aria-modal="true" aria-label="Dialog">
+      {children}
+    </div>
+  );
+}
+```
+
+Skip navigation link -- first focusable element on the page:
+
+```html
+<a href="#main-content" class="sr-only focus:not-sr-only focus:absolute focus:top-2 focus:left-2">
+  Skip to main content
+</a>
+```
+
+### Color Contrast
+
+WCAG AA requires 4.5:1 for normal text, 3:1 for large text (18px+ or 14px+ bold):
+
+```css
+/* BAD -- light gray on white: 2.1:1 ratio */
+.subtle-text { color: #999; background: #fff; }
+
+/* GOOD -- dark gray on white: 7.4:1 ratio */
+.body-text { color: #374151; background: #fff; }
+
+/* Never use color alone to convey information */
+.error { color: #dc2626; }
+.error::before { content: "! "; font-weight: bold; }
+```
+
+### Screen Reader Best Practices
+
+```tsx
+// Visually hidden but announced by screen readers
+<span className="sr-only">3 items in cart</span>
+
+// Image alt text -- describe the content, not the format
+<img alt="Bar chart showing revenue growth from $2M to $5M in Q3" src="chart.png" />
+// Decorative images get empty alt
+<img alt="" src="decorative-border.png" role="presentation" />
+
+// Form labels -- every input needs one
+<label htmlFor="email">Email address</label>
+<input id="email" type="email" aria-describedby="email-hint" />
+<p id="email-hint">We will never share your email.</p>
+
+// Error messages linked to inputs
+<input
+  id="password"
+  type="password"
+  aria-invalid={!!error}
+  aria-describedby={error ? "password-error" : undefined}
+/>
+{error && <p id="password-error" role="alert">{error}</p>}
+```
+
+### Focus Management
+
+When content changes dynamically, manage focus so users are not lost:
+
+```typescript
+// After deleting an item from a list, focus the next item
+function handleDelete(index: number) {
+  deleteItem(index);
+  const nextItem = listRef.current?.children[Math.min(index, items.length - 1)];
+  (nextItem as HTMLElement)?.focus();
+}
+
+// After SPA navigation, focus the new page heading
+useEffect(() => {
+  const heading = document.querySelector("h1");
+  heading?.setAttribute("tabindex", "-1");
+  heading?.focus();
+}, [pathname]);
+```
+
+## Examples
+
+| Issue | Fix | WCAG Criterion |
+|-------|-----|---------------|
+| Clickable div | Replace with `<button>` | 2.1.1 Keyboard |
+| No visible focus indicator | Add `:focus-visible` outline | 2.4.7 Focus Visible |
+| Error shown only in red | Add icon + text + `aria-invalid` | 1.4.1 Use of Color |
+| Modal does not trap focus | Add focus trap + Escape to close | 2.4.3 Focus Order |
+| Dynamic content not announced | Use `aria-live="polite"` | 4.1.3 Status Messages |
+| Image without alt text | Add descriptive alt | 1.1.1 Non-text Content |
+
+## Checklist
+- [ ] All interactive elements reachable and operable via keyboard
+- [ ] Every form input has a visible `<label>` or `aria-label`
+- [ ] Color contrast meets WCAG AA (4.5:1 normal, 3:1 large text)
+- [ ] Color is never the sole means of conveying information
+- [ ] Images have descriptive alt text (or empty alt for decorative)
+- [ ] Modals trap focus and close with Escape
+- [ ] Skip navigation link is the first focusable element
+- [ ] Dynamic content uses `aria-live` for announcements