best-practice

name	best-practice
description	Cross-cutting best practices enforcement across code, templates, skills, prompts, scripts, documentation, pages, and design. The enforcement layer that catches violations any specialist might miss. Do NOT use for deep code review methodology (use code-review), auth guard selection (use nextauth-patterns), SQL injection prevention (use security-scanning), PII masking (use gdpr-compliance), accessibility implementation depth (use a11y), or financial semantics (use code-logic).
license	MIT
compatibility	Applies to any web application codebase using TypeScript, React, and Next.js App Router. The cross-domain enforcement priorities (security, a11y, performance, design system, testing, DevOps, AI/LLM) are framework-agnostic; the Next.js section is specific to the App Router pattern.
allowed-tools	Read Grep Bash
metadata	{"metadata":"{\"schema_version\":6,\"version\":\"1.2.0\",\"type\":\"capability\",\"category\":\"quality\",\"domain\":\"quality/cross-domain\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-18\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-18\\\\\\\",\\\\\\\"truth_source_hashes\\\\\\\":{}}\",\"eval_artifacts\":\"none\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"stable\",\"keywords\":\"[\\\\\\\"best practice\\\\\\\",\\\\\\\"best practices\\\\\\\",\\\\\\\"code quality\\\\\\\",\\\\\\\"quality enforcement\\\\\\\",\\\\\\\"code review checklist\\\\\\\",\\\\\\\"OWASP\\\\\\\",\\\\\\\"WCAG\\\\\\\",\\\\\\\"Core Web Vitals\\\\\\\",\\\\\\\"SOLID principles\\\\\\\",\\\\\\\"clean code\\\\\\\",\\\\\\\"visual hierarchy\\\\\\\",\\\\\\\"typographic hierarchy\\\\\\\",\\\\\\\"color hierarchy\\\\\\\",\\\\\\\"UI composition\\\\\\\",\\\\\\\"cross-cutting concerns\\\\\\\",\\\\\\\"quality gate\\\\\\\",\\\\\\\"enforcement layer\\\\\\\"]\",\"examples\":\"[\\\\\\\"reviewing a pull request for correctness, security, and style\\\\\\\",\\\\\\\"creating a new React component and checking it against quality standards\\\\\\\",\\\\\\\"auditing an existing feature for WCAG compliance and performance regressions\\\\\\\",\\\\\\\"writing tests and verifying coverage shape (unit / integration / e2e pyramid)\\\\\\\",\\\\\\\"authoring a new skill and checking it has structured scope, evals, and examples\\\\\\\",\\\\\\\"adding a new Next.js Server Action and verifying it has Zod validation and auth check\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"reviewing PR feedback phrasing and comment classification (use code-review)\\\\\\\",\\\\\\\"choosing between requireAuth, requireOrgAuth, and withOrgAuth (use nextauth-patterns)\\\\\\\",\\\\\\\"implementing SQL injection prevention or webhook HMAC verification (use security-scanning)\\\\\\\",\\\\\\\"designing the APCA contrast ratio for a new color palette (use color-science)\\\\\\\",\\\\\\\"implementing the font loading strategy and vertical rhythm (use typography)\\\\\\\",\\\\\\\"deciding what quality means per artifact type — code vs skill vs prompt (use craft-doctrine)\\\\\\\"]\",\"relations\":\"{\\\\\\\"adjacent\\\\\\\":[\\\\\\\"code-review\\\\\\\",\\\\\\\"security-scanning\\\\\\\",\\\\\\\"a11y\\\\\\\",\\\\\\\"design-guide\\\\\\\",\\\\\\\"composition-theory\\\\\\\",\\\\\\\"color-science\\\\\\\",\\\\\\\"visual-design\\\\\\\",\\\\\\\"typography\\\\\\\",\\\\\\\"copywriting\\\\\\\",\\\\\\\"semantics\\\\\\\",\\\\\\\"ui-ux\\\\\\\",\\\\\\\"next-best-practices\\\\\\\"],\\\\\\\"boundary\\\\\\\":[],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"code-review\\\\\\\",\\\\\\\"security-scanning\\\\\\\"]}\",\"grounding\":\"{\\\\\\\"domain_object\\\\\\\":\\\\\\\"Cross-cutting quality enforcement across 14 domains\\\\\\\",\\\\\\\"grounding_mode\\\\\\\":\\\\\\\"hybrid\\\\\\\",\\\\\\\"truth_sources\\\\\\\":[],\\\\\\\"failure_modes\\\\\\\":[\\\\\\\"specialist_boundary_gaps\\\\\\\",\\\\\\\"heading_hierarchy_violations\\\\\\\",\\\\\\\"hardcoded_values_bypass_token_system\\\\\\\",\\\\\\\"server_actions_treated_as_internal\\\\\\\",\\\\\\\"dead_tests_accumulate\\\\\\\"],\\\\\\\"evidence_priority\\\\\\\":\\\\\\\"general_knowledge_first\\\\\\\"}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"declared\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":180,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v6\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/best-practice/SKILL.md\"}","skill_graph_source_repo":"https://github.com/jacob-balslev/skill-graph","skill_graph_protocol":"Skill Metadata Protocol v4","skill_graph_project":"Skill Graph","skill_graph_canonical_skill":"skills/best-practice/SKILL.md"}

Best Practice — Cross-Cutting Quality Enforcement

Domain Context

What is this skill? Cross-cutting best practices enforcement across code, templates, skills, prompts, scripts, documentation, pages, and design. The enforcement layer that catches violations any specialist might miss.

Coverage

Cross-cutting best practices enforcement across code, templates, skills, prompts, scripts, documentation, pages, and design. The sections below contain the detailed rules, examples, and boundaries for using this skill correctly.

Coverage (14 domains)

Code quality (SOLID, strict TypeScript, DRY/KISS), documentation (ADRs, self-documenting names, TSDoc), security (OWASP Top 10:2025, secret management, input validation), accessibility (WCAG 2.2, semantic HTML, keyboard operability), performance (Core Web Vitals, code splitting, image optimization), design systems (token hierarchy, dark mode, composable APIs), testing (pyramid shape, behavior-not-implementation, coverage guardrails), DevOps (trunk-based development, progressive delivery, pipeline-as-code), AI/LLM skill design (RCCF structure, eval methodology, scope boundaries), Next.js App Router patterns (Server Components default, Server Action security, explicit caching), UX & UI composition (F-pattern for data surfaces, one L1 focal point per zone, density-first spacing), visual hierarchy (surface layering, card/banner depth, information density vs whitespace), typographic hierarchy (6-level heading contract, Minor Third scale, 4 canonical weights, h6 micro-labels), and color hierarchy (greyscale chrome, financial-only semantic color, triple encoding for colorblind safety).

Authority: Cross-domain quality gate. Does not override specialist skills — catches violations that fall between specialist boundaries. Defer to specialists for depth. Scope: "Small focused changes" means scope discipline, NOT code reduction. See craft-doctrine for the enrichment principle.

Philosophy

This skill exists because quality violations most often occur at the boundaries between specialist domains — a developer focuses on getting the TypeScript right but ships a <div onClick> instead of a <button>, or nails the component logic but hardcodes a hex color. No single specialist skill catches all of these; each covers its own depth. Without a cross-cutting enforcement layer, agents produce code that passes within any one domain but fails the "would a senior engineer approve this PR?" test. Observed failure modes that motivated this skill: SQL injection via string interpolation passing TypeScript strict mode, skipped test.skip entries accumulating into permanent dead tests, Server Actions treated as internal functions despite being public HTTP endpoints, and heading hierarchy violations slipping through because neither the a11y skill nor the design-guide skill owned the overlap zone. This skill is the net that catches what falls between specialist boundaries.