frontend-guardrails

What this skill does

# Frontend Guardrails

Without explicit standards, frontend code drifts: the same logic in three places (so one bug needs three fixes), inconsistent colors and fonts, backend concerns leaking into the UI, secrets and user data ending up in the browser. This skill is the standing instruction set that prevents that, so professional output is the *default* and requires no extra prompting.

**Compose, don't reinvent.** This skill is opinionated policy, not a re-implementation of existing tools. Where a mature linter, formatter, auditor, MCP, or companion skill already enforces one of these standards, prefer wiring it in over duplicating its work — see `references/ecosystem.md` for the recommended ecosystem and how each principle maps to it.

## How to use this skill

1. **Detect the stack first.** Identify the framework, styling approach, and state library from `package.json`, config files, and existing components. Never impose a stack the project does not use.
2. **Read the matching framework reference** for syntax-level guidance:
   - React / Next.js → `references/react.md`
   - Vue / Nuxt → `references/vue.md`
   - Angular → `references/angular.md`
   - Svelte / SvelteKit → `references/svelte.md`
   - Anything else (plain JS, SolidJS, etc.) → apply the principles below; the framework files show how the same principles map to syntax.
3. **Apply the universal principles** (below) to every task.
4. **Read the topic reference when the task touches that area** — these hold the deep detail:
   - Security-sensitive work (auth, user data, env vars, tokens) → `references/security.md`
   - Notifications, toasts, or user feedback → `references/notifications.md`
   - Accessibility → `references/accessibility.md`
5. **Run the self-audit** (final section) before declaring any task done.

---

## Scale rigor to the project (read first)

Match the depth of these standards to the project's size and maturity. Imposing enterprise rigor on a small or beginner project is itself a violation of principle 16 — over-engineering.

- **Always apply the fundamentals, at any size:** reusability/DRY, consistent design tokens, responsiveness, the security basics, professional polish, not shipping broken code, and not over-engineering.
- **Don't impose heavyweight infrastructure on projects that don't use it.** Do not introduce CI pipelines, test suites, TypeScript, build tooling, design-system infrastructure, or supply-chain scanning into a project that doesn't already have them unless the user asks or the project clearly warrants it. Detect what exists, match it, and grow rigor only as the project grows.
- **For beginners and non-developers, prefer sensible defaults over interrogation.** When a technical choice arises (state approach, folder structure, library), pick a reasonable default and explain it in one line rather than quizzing someone on jargon they may not know. Ask only when a choice genuinely cannot be made for them.
- **Keep ecosystem recommendations opt-in and needs-gated.** Offer tools (CI, hooks, CodeRabbit, scanners, Context7) when they actually fit the project — never as a checklist the user must satisfy or feel they've failed.

---

## Precedence — these are baselines, not mandates

The user's explicit instructions and the project's existing conventions always win over this skill's defaults. These principles are a portable baseline to fall back on, not commandments to impose.

- When a principle conflicts with an established project choice or a clear user instruction, follow the project/user — and if the trade-off is genuinely risky, flag it in one line rather than silently overriding either direction.
- Engineering is trade-offs. A deliberate, reasoned exception — accepted duplication, a test skipped on a throwaway spike, `any` at an untyped boundary — is not a violation. Don't "correct" intentional decisions.
- This skill governs the *AI's* defaults so output stays disciplined and consistent across sessions and teammates; it is not here to override an experienced developer's judgment.

## Hard rules vs sensible defaults

Not everything below carries equal weight. Distinguish the two:

- **Non-negotiable (don't bend without explicit, informed sign-off):** the security fundamentals — no secrets in client code, the backend enforces authorization, no unsanitized HTML, least data exposure — and not shipping broken code (it builds and typechecks locally with no errors).
- **Sensible defaults (defer to the project when it differs):** everything stylistic or architectural — toast placement, font count, when design tokens are worth it, SSR vs SSG/ISR, `any` usage, state-management and folder choices. Apply these when the project has no opinion; yield when it does.

This is a deliberately tight baseline, not an exhaustive checklist — it omits topics like i18n, error monitoring, and visual-regression testing on purpose, to stay lean and composable. Add them per project when needed.

---

## Surface the trade-off, then let the user decide

When following the user's request would conflict with a fundamental or steer toward a likely downstream problem, don't silently comply and don't silently override. Make the trade-off visible, then defer to their choice:

1. **Name the risk concretely** — what specifically could go wrong, and how it could grow into a real problem later. Be concrete, not vague: e.g. "storing the auth token in `localStorage` means any XSS bug anywhere in the app becomes full account takeover," or "this duplicated logic in three files means a future fix has to be made in all three — easy to miss one."
2. **State the cleaner approach in a sentence** — what you'd do instead and why.
3. **Ask whether to apply it or continue as requested — and honor the answer.** The user always decides; your job is to surface the choice before it gets baked in, not to insist.

Calibrate so this helps rather than nags:
- Only interrupt for genuine fundamentals or real downstream risks (security, data exposure, code that won't build, an architectural choice that's costly to unwind later). For stylistic or architectural defaults the project hasn't decided, just pick a sensible option and mention it in one line — don't turn every small choice into a question.
- After completing work, briefly note which standards shaped the result (one line, skipped for trivial tasks) — so the user can see what was applied without reading a lecture.
- If the user has already chosen to proceed their way, respect it and move on; don't re-litigate the same point.

---

## Universal principles

**1. Reusability / DRY — "one fix, not five."** If you would write the same markup, logic, or value twice, extract it once (a component, a hook/function, a token). Before building new UI, search for an existing component to reuse or extend. Duplication means fixing the same bug in many places.

**2. Component architecture & separation of concerns.** Build small, single-responsibility components that compose. Keep presentation, logic, and data access in separate layers — data fetching belongs in a clear layer, not inside presentational components. Name files consistently with one convention.

**3. Consistency through design tokens.** Never hardcode raw colors, font sizes, spacing, or radii. Reference named tokens (CSS variables, a theme object, or config) so every value has one source of truth. Inconsistent values are the hallmark of unpolished work.

**4. Responsiveness.** Design mobile-first against the project's defined breakpoints; never assume a single screen size. Prefer fluid units and flex/grid over fixed pixel widths. Verify nothing overflows, overlaps, or becomes unreadable at narrow, medium, and wide widths.

**5. Professional polish.** Every page needs a meaningful `<title>`, the favicon/logo in the tab, and viewport + description meta (Open Graph for shareable pages). Always handle loading and empty states — never show a blank or broken screen. (Accessibility basics are covered in principle 11.)

*