From 3437b7d617c0468e5a4886102e556f685ab1b595 Mon Sep 17 00:00:00 2001
From: Geordano Polanco <geordano.pr@gmail.com>
Date: Thu, 12 Feb 2026 02:08:08 +0100
Subject: [PATCH] feat(rules): add P1 rules (design, a11y, performance, git,
 debugging, auth)

Six new rules for the registry:
- frontend/design-guidelines: layout, typography, color, components, responsive
- frontend/accessibility: semantic HTML, ARIA, keyboard, visual
- frontend/performance: loading, rendering, assets, monitoring
- workflow/git-conventions: commits, branches, pull requests
- workflow/debugging: process, techniques, logging
- security/auth-patterns: authentication, sessions, authorization, pitfalls
---
 content/rules/README.md                     |   6 ++
 content/rules/frontend/accessibility.md     |  81 +++++++++++++++
 content/rules/frontend/design-guidelines.md | 106 ++++++++++++++++++++
 content/rules/frontend/performance.md       |  77 ++++++++++++++
 content/rules/security/auth-patterns.md     |  81 +++++++++++++++
 content/rules/workflow/debugging.md         |  71 +++++++++++++
 content/rules/workflow/git-conventions.md   |  62 ++++++++++++
 7 files changed, 484 insertions(+)
 create mode 100644 content/rules/frontend/accessibility.md
 create mode 100644 content/rules/frontend/design-guidelines.md
 create mode 100644 content/rules/frontend/performance.md
 create mode 100644 content/rules/security/auth-patterns.md
 create mode 100644 content/rules/workflow/debugging.md
 create mode 100644 content/rules/workflow/git-conventions.md

diff --git a/content/rules/README.md b/content/rules/README.md
index 8ec46af..aeba131 100644
--- a/content/rules/README.md
+++ b/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
 
diff --git a/content/rules/frontend/accessibility.md b/content/rules/frontend/accessibility.md
new file mode 100644
index 0000000..d52a2ba
--- /dev/null
+++ b/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.
diff --git a/content/rules/frontend/design-guidelines.md b/content/rules/frontend/design-guidelines.md
new file mode 100644
index 0000000..c12685c
--- /dev/null
+++ b/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.
diff --git a/content/rules/frontend/performance.md b/content/rules/frontend/performance.md
new file mode 100644
index 0000000..72918c4
--- /dev/null
+++ b/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`.
diff --git a/content/rules/security/auth-patterns.md b/content/rules/security/auth-patterns.md
new file mode 100644
index 0000000..78d0382
--- /dev/null
+++ b/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.
diff --git a/content/rules/workflow/debugging.md b/content/rules/workflow/debugging.md
new file mode 100644
index 0000000..55ccb50
--- /dev/null
+++ b/content/rules/workflow/debugging.md
@@ -0,0 +1,71 @@
+---
+name: debugging
+description: "Systematic debugging methodology for AI coding agents"
+version: "0.1.0"
+scope: workflow
+tags: [workflow, debugging, methodology]
+---
+
+## Process
+
+- Follow a systematic order: reproduce, isolate, diagnose,
+  fix, verify, document. Skipping steps leads to patches
+  that mask the real problem.
+
+- Always reproduce the bug before attempting a fix. If you
+  cannot reproduce it, you cannot verify the fix. Get the
+  exact steps, inputs, and environment.
+
+- Isolate the problem to the smallest reproducible case.
+  Remove unrelated code, dependencies, and data until only
+  the bug remains.
+
+- Make one change at a time. Changing five things and hoping
+  something works is not debugging, it is guessing. Change
+  one variable, test, repeat.
+
+- If a fix works but you cannot explain why, do not accept
+  it. Understand the root cause. Unexplained fixes hide
+  deeper issues that will resurface.
+
+## Techniques
+
+- Read the full error message and stack trace before doing
+  anything else. The answer is often in the message you
+  skipped.
+
+- Use binary search to locate bugs in large codebases.
+  Comment out half the code, test, narrow down which half
+  contains the bug, repeat.
+
+- Check your assumptions first. Verify that the function
+  is actually called, the variable has the value you expect,
+  and the branch you think runs actually executes.
+
+- Rubber duck it. Explain the problem out loud, step by
+  step. Forcing yourself to articulate the expected vs actual
+  behavior often reveals the gap.
+
+- If you are stuck for more than 30 minutes without progress,
+  change your approach. Re-read the documentation, check
+  recent changes in git, or step away and come back fresh.
+
+## Logging
+
+- Log at system boundaries: API calls, database queries,
+  event handlers, and external service integrations. These
+  are where bugs hide.
+
+- Use log levels consistently: `error` for failures that
+  need immediate attention, `warn` for unexpected but
+  recoverable situations, `info` for normal flow milestones,
+  `debug` for detailed diagnostic data.
+
+- Include context in log messages: the function name, relevant
+  IDs, and input values. A log that says "error occurred"
+  is useless. A log that says "payment failed for order
+  abc-123: insufficient funds" is actionable.
+
+- Never ship debugging logs to production. Remove
+  `console.log` and `print` statements before committing.
+  Use a structured logging library for persistent logs.
diff --git a/content/rules/workflow/git-conventions.md b/content/rules/workflow/git-conventions.md
new file mode 100644
index 0000000..75aee9e
--- /dev/null
+++ b/content/rules/workflow/git-conventions.md
@@ -0,0 +1,62 @@
+---
+name: git-conventions
+description: "Git workflow and commit conventions"
+version: "0.1.0"
+scope: workflow
+tags: [git, workflow, conventions]
+---
+
+## Commits
+
+- Follow Conventional Commits: `feat:`, `fix:`, `docs:`,
+  `chore:`, `refactor:`, `test:`. Add an optional scope
+  in parentheses: `feat(auth): add login flow`.
+
+- Write the subject line in imperative mood: "add feature",
+  not "added feature" or "adding feature". Keep it under
+  72 characters.
+
+- One commit equals one logical change. Do not mix a refactor
+  with a feature, or a bug fix with a formatting cleanup.
+  Each commit should be reviewable in isolation.
+
+- Write a body when the subject alone does not explain why.
+  Separate subject from body with a blank line. The body
+  explains motivation, not implementation.
+
+- Never commit secrets, `.env` files, `node_modules`,
+  build artifacts, or generated files. Add them to
+  `.gitignore` before the first commit.
+
+## Branches
+
+- Use prefixed branch names: `feat/`, `fix/`, `chore/`,
+  `docs/`, `refactor/`. Follow with a short kebab-case
+  slug: `feat/add-login-flow`.
+
+- Never commit directly to `main` or `master`. Always create
+  a feature branch and merge through a pull request.
+
+- Keep branches short-lived. A branch that lives for weeks
+  will accumulate merge conflicts and delay feedback.
+  Merge early and often.
+
+- Delete branches after merging. Stale branches clutter
+  the repo and confuse contributors.
+
+## Pull Requests
+
+- Write a descriptive title that summarizes the change.
+  The description should explain what changed, why, and
+  how to test it.
+
+- Keep PRs small and focused. One feature or fix per PR.
+  Large PRs take longer to review and are more likely to
+  introduce bugs.
+
+- Use squash merge for feature branches to keep the main
+  branch history clean. Use merge commits for release
+  branches when you need to preserve individual commits.
+
+- Do not approve your own PR. Request review from at least
+  one teammate. Address all review comments before merging.