feat(rules): add P1 rules (design, a11y, performance, git, debugging, auth)

content/rules/README.md

@@ -12,6 +12,12 @@ Rules for AI coding agents, distributed via `devw add`.
 | `css/tailwind` | CSS | Utility-first Tailwind conventions | `devw add css/tailwind` |
 | `testing/vitest` | Testing | Vitest testing patterns | `devw add testing/vitest` |
 | `security/supabase-rls` | Security | Supabase RLS enforcement | `devw add security/supabase-rls` |
+| `frontend/design-guidelines` | Frontend | UI design principles for AI coding agents | `devw add frontend/design-guidelines` |
+| `frontend/accessibility` | Frontend | Accessibility best practices | `devw add frontend/accessibility` |
+| `frontend/performance` | Frontend | Frontend performance optimization rules | `devw add frontend/performance` |
+| `workflow/git-conventions` | Workflow | Git workflow and commit conventions | `devw add workflow/git-conventions` |
+| `workflow/debugging` | Workflow | Systematic debugging methodology | `devw add workflow/debugging` |
+| `security/auth-patterns` | Security | Authentication and authorization best practices | `devw add security/auth-patterns` |
 
 ## Usage
 

content/rules/frontend/accessibility.md

@@ -0,0 +1,81 @@
+---
+name: accessibility
+description: "Accessibility best practices for AI coding agents"
+version: "0.1.0"
+scope: conventions
+tags: [frontend, accessibility, a11y, html]
+---
+
+## Semantic HTML
+
+- Use the correct HTML element for the job. `<button>` for
+  actions, `<a>` for navigation, `<input>` for data entry.
+  Never put an `onClick` on a `<div>` or `<span>`.
+
+- Structure headings in order: one `<h1>` per page, then
+  `<h2>`, `<h3>`, and so on. Never skip heading levels
+  for styling purposes.
+
+- Use landmark elements: `<nav>`, `<main>`, `<aside>`,
+  `<header>`, `<footer>`. Screen readers use these to
+  let users jump between sections.
+
+- Use `<ul>` or `<ol>` for lists of items, `<table>` for
+  tabular data, `<form>` to wrap form controls. Semantic
+  structure communicates meaning without visual cues.
+
+## ARIA
+
+- Use ARIA only when native HTML cannot express the semantics.
+  A `<button>` is always better than `<div role="button">`.
+
+- Add `aria-label` to icon-only buttons and links that have
+  no visible text. The label must describe the action, not
+  the icon (e.g. "Close dialog", not "X icon").
+
+- Use `aria-describedby` to associate help text or error
+  messages with form inputs. Use `aria-live="polite"` on
+  regions that update dynamically so screen readers announce
+  changes.
+
+- Never use `aria-hidden="true"` on focusable elements.
+  If something is hidden from assistive tech, it must also
+  be removed from the tab order.
+
+## Keyboard
+
+- Every interactive element must be reachable with Tab and
+  activable with Enter or Space. Test by putting your mouse
+  in a drawer and navigating with keyboard only.
+
+- Maintain a visible focus indicator on all interactive
+  elements. Never set `outline: none` without providing a
+  custom focus style that meets contrast requirements.
+
+- Trap focus inside modals and dialogs. When a modal opens,
+  focus the first focusable element. When it closes, return
+  focus to the trigger element.
+
+- Support Escape to close modals, dropdowns, and popovers.
+  Users expect it and it is required by WCAG.
+
+## Visual
+
+- Meet WCAG contrast minimums: 4.5:1 for normal text
+  (under 18px or 14px bold), 3:1 for large text and
+  UI components.
+
+- Never rely on color alone to convey information. Pair
+  color with icons, text labels, or patterns. Error states
+  need both red color and an error icon or message.
+
+- Write descriptive alt text for informational images.
+  Describe what the image communicates, not what it looks
+  like. Use `alt=""` for purely decorative images.
+
+- Every form input must have a visible `<label>` element
+  linked via `for`/`id`. Placeholder text is not a label
+  and disappears on input.
+
+- Ensure touch targets are at least 44x44px. Small links
+  and icon buttons need padding to meet this minimum.

content/rules/frontend/design-guidelines.md

@@ -0,0 +1,106 @@
+---
+name: design-guidelines
+description: "UI design principles for AI coding agents"
+version: "0.1.0"
+scope: design
+tags: [frontend, design, ui, ux]
+---
+
+## Layout
+
+- Use a consistent spacing system based on a 4px or 8px grid.
+  Every margin, padding, and gap should be a multiple of the
+  base unit. No magic numbers.
+
+- Establish clear visual hierarchy with size, weight, and
+  spacing. The most important element on the page should be
+  immediately obvious without reading a single word.
+
+- Use whitespace deliberately to group related content and
+  separate unrelated content. Whitespace is a design tool,
+  not leftover space.
+
+- Limit content width for readability. Body text should not
+  exceed 65-75 characters per line. Use `max-width` on
+  text containers.
+
+## Typography
+
+- Use at most two font families: one for headings, one for
+  body. A single family with varied weights is often enough.
+
+- Define a type scale and stick to it. Use 4-6 distinct sizes
+  with a consistent ratio (e.g. 1.25 or 1.333). Never pick
+  arbitrary font sizes.
+
+- Set line-height relative to font size: 1.5 for body text,
+  1.2-1.3 for headings. Tighter leading on large text, looser
+  on small text.
+
+- Use font weight to create contrast, not font size alone.
+  Pair a bold heading with regular body text rather than
+  relying on size differences.
+
+## Color
+
+- Define a limited palette: one primary, one neutral scale,
+  and semantic colors (success, error, warning, info).
+  Resist adding colors outside this set.
+
+- Ensure sufficient contrast ratios: 4.5:1 minimum for body
+  text, 3:1 for large text and UI elements. Test with a
+  contrast checker, do not eyeball it.
+
+- Use color semantically. Red means destructive or error,
+  green means success, yellow means warning. Do not repurpose
+  semantic colors for decoration.
+
+- Support dark mode from the start if the project requires it.
+  Use CSS custom properties or theme tokens for all colors,
+  never hardcode hex values in components.
+
+## Components
+
+- Build components with clear visual states: default, hover,
+  focus, active, disabled, and loading. Every interactive
+  element needs at least hover and focus.
+
+- Use consistent border-radius, shadow, and border values
+  across all components. Define these as design tokens and
+  reference them everywhere.
+
+- Make clickable areas at least 44x44px on touch devices.
+  Pad small icons and links to meet this minimum target size.
+
+- Show loading and empty states. Never leave users staring
+  at a blank screen or an unresponsive button.
+
+## Responsive
+
+- Design mobile-first. Start with the smallest screen and
+  add complexity at wider breakpoints using `min-width`
+  media queries.
+
+- Use 2-3 breakpoints maximum. More breakpoints create more
+  maintenance and more inconsistency. Fluid layouts with
+  `clamp()` reduce the need for breakpoints.
+
+- Never hide critical content or functionality on mobile.
+  Adapt the layout, do not remove features.
+
+- Test at real device widths (320px, 375px, 768px, 1024px,
+  1440px), not just at breakpoint boundaries.
+
+## Taste
+
+- Make concrete design decisions. Pick a specific visual
+  direction and commit to it. Vague, generic aesthetics
+  scream "AI-generated."
+
+- Avoid gratuitous gradients, excessive rounded corners,
+  and decorative elements that do not serve the content.
+  Restraint is a design skill.
+
+- Steal from good design, not from templates. Reference
+  real products you admire and adapt their patterns to
+  your context.

content/rules/frontend/performance.md

@@ -0,0 +1,77 @@
+---
+name: performance
+description: "Frontend performance optimization rules"
+version: "0.1.0"
+scope: performance
+tags: [frontend, performance, core-web-vitals]
+---
+
+## Loading
+
+- Lazy load routes and heavy components with dynamic imports.
+  Only the code needed for the current view should load
+  on initial page render.
+
+- Defer non-critical scripts with `defer` or `async`.
+  Third-party analytics, chat widgets, and tracking pixels
+  should never block the critical rendering path.
+
+- Preload critical assets: the main font, hero image, and
+  above-the-fold CSS. Use `<link rel="preload">` with the
+  correct `as` attribute.
+
+- Avoid waterfalls. Do not fetch data, then fetch more data
+  based on the result, then render. Parallelize requests and
+  colocate data fetching with the component that needs it.
+
+## Rendering
+
+- Reserve explicit dimensions for images, videos, and embeds
+  with `width` and `height` attributes or CSS `aspect-ratio`.
+  This prevents layout shifts (CLS).
+
+- Minimize DOM depth and node count. Deeply nested markup
+  slows style recalculation and layout. Flatten structure
+  where possible.
+
+- Avoid forced synchronous layouts. Do not read layout
+  properties (`offsetHeight`, `getBoundingClientRect`) then
+  immediately write styles in a loop.
+
+- Minimize client-side JavaScript that blocks interactivity.
+  Move computation to the server, web workers, or build time
+  when possible.
+
+## Assets
+
+- Use modern image formats: WebP or AVIF with a fallback.
+  Serve responsive images with `srcset` and `sizes` to avoid
+  sending oversized files to small screens.
+
+- Load images below the fold with `loading="lazy"`. Eager
+  load only the hero image and above-the-fold content.
+
+- Limit fonts to two families maximum. Preload the primary
+  font and use `font-display: swap` to prevent invisible
+  text during load.
+
+- Prefer build-time or utility-first CSS over runtime CSS-in-JS.
+  Runtime style injection adds JavaScript overhead and delays
+  first paint.
+
+## Monitoring
+
+- Do not optimize without measuring. Run Lighthouse or
+  WebPageTest before and after changes. Optimize the
+  bottleneck, not what you assume is slow.
+
+- Track Core Web Vitals in production: LCP under 2.5s,
+  INP under 200ms, CLS under 0.1. These are the metrics
+  that affect real users.
+
+- Set performance budgets for bundle size and load time.
+  Fail the build or flag in CI when budgets are exceeded.
+
+- Cache aggressively. Use content hashes in asset filenames
+  for long-lived cache headers. Serve static assets from a
+  CDN with proper `Cache-Control`.

content/rules/security/auth-patterns.md

@@ -0,0 +1,81 @@
+---
+name: auth-patterns
+description: "Authentication and authorization best practices"
+version: "0.1.0"
+scope: security
+tags: [security, auth, authentication, authorization]
+---
+
+## Authentication
+
+- Never store passwords in plain text. Always hash with
+  bcrypt, scrypt, or argon2 using a unique salt per password.
+
+- Use short-lived access tokens (15 minutes or less) paired
+  with longer-lived refresh tokens. Rotate refresh tokens
+  on every use.
+
+- Never store sensitive tokens in `localStorage` or
+  `sessionStorage`. Use `httpOnly`, `Secure`, `SameSite`
+  cookies for tokens that grant access to protected resources.
+
+- For SPAs, use OAuth 2.0 Authorization Code flow with PKCE.
+  Never use Implicit flow, it exposes tokens in the URL.
+
+- Offer TOTP-based two-factor authentication as a minimum.
+  Avoid SMS-based 2FA, it is vulnerable to SIM swapping
+  and interception.
+
+## Sessions
+
+- Invalidate all sessions and tokens when a user changes
+  their password, resets credentials, or explicitly logs out.
+
+- Set absolute session timeouts. No session should live
+  indefinitely regardless of activity. Force re-authentication
+  for sensitive operations.
+
+- Bind sessions to the user agent and IP range when possible.
+  Reject sessions that suddenly appear from a different
+  context.
+
+- Store session data server-side. The session ID in the
+  cookie should be an opaque random value, not a JWT
+  containing user data.
+
+## Authorization
+
+- Verify permissions on the server for every request. Never
+  trust the client to enforce access control. Hiding a button
+  in the UI is not authorization.
+
+- Apply the principle of least privilege. Grant the minimum
+  permissions required for the task. Default to deny and
+  explicitly allow.
+
+- Check authorization at the resource level, not just the
+  route level. A user who can access `/api/orders` may not
+  be authorized to access `/api/orders/123` if that order
+  belongs to someone else.
+
+- Log all authorization failures, privilege escalations, and
+  sensitive actions. These logs are your audit trail and your
+  early warning system.
+
+## Common Pitfalls
+
+- Apply rate limiting to all authentication endpoints: login,
+  registration, password reset, and token refresh. Use
+  exponential backoff after repeated failures.
+
+- Protect every state-changing request against CSRF. Use
+  CSRF tokens or `SameSite=Strict` cookies. GET requests
+  must never mutate state.
+
+- Never reveal whether an account exists in error responses.
+  "Invalid email or password" for login, "If this email
+  exists, we sent a reset link" for password reset.
+
+- Validate and sanitize all auth-related input on the server.
+  Email format, password length, token format. Client-side
+  validation is a convenience, not a security measure.