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).
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.
Cross-Domain Synergy
As the baseline enforcement layer, this skill connects:
ui-ux & composition-theory: Enforcing layout rules (one L1 focal point, F-pattern for data, density-first spacing).
visual-design & design-guide: Surface hierarchy, card depth, information density vs whitespace balance.
typography & semantics: Strict adherence to 6-level heading hierarchy, Minor Third scale, readable names.
Every // TODO must reference a ticket: // TODO(SH-1234)
See adr for ADR creation methodology. See doc-updater for the documentation update protocol.
3. Security (OWASP Top 10:2025)
Priority
Rule
Check
A01
Broken Access Control
Every endpoint verifies auth AND authz; default-deny
A03
Supply Chain
No high/critical CVEs; pin dependency versions
A05
Injection
Parameterized queries only; Zod validation on all input
A10
Exception Handling
No stack traces to clients; all errors caught server-side
—
Secret management
No secrets in source; .env* in .gitignore
Deep reference: references/security-checklist.md. See security-scanning for SQL injection prevention, CSRF, and webhook security details. See gdpr-compliance for PII masking, per-provider erasure handlers, and retention enforcement.
4. Accessibility (WCAG 2.2)
Rule
Standard
Check
Semantic HTML first
WCAG 4.1.2
<button> not <div onClick>, native <dialog>, <nav>
Keyboard operable
WCAG 2.1.1
All functionality via Tab/Enter/Space/Arrows; no traps
Color contrast
WCAG 1.4.3
4.5:1 text, 3:1 UI components
Target size
WCAG 2.5.8
24px WCAG minimum; Sales Hub enforces 44x44px
Heading hierarchy
WCAG 1.3.1
Sequential h1>h2>h3, no skipping, one h1 per page
Deep reference: references/accessibility-checklist.md. See a11y for Sales Hub 44px targets, Axe-Core Playwright tests, focus-ring system, reduced-motion strategy, and live-region placement.
5. Performance
Rule
Threshold
Check
LCP
<2.5s
No lazy-load on above-fold images
INP
<200ms
No main-thread tasks >50ms; defer non-critical JS
CLS
<0.1
Images have width/height; no layout shifts
Bundle discipline
Monitor in CI
Dynamic import() for routes; no full-library imports
Image optimization
AVIF/WebP
next/image with proper sizing; loading="lazy" below fold
Deep reference: references/performance-checklist.md. See react-best-practices for 57 detailed performance optimization rules across 8 categories.
6. Design System
Rule
Enforcement
Three-tier token hierarchy
Primitive > Semantic > Component; never use primitives in components
No hardcoded values
All colors, spacing, typography via tokens — never raw hex or px
Dark mode via CSS custom properties
:root light, [data-theme="dark"] overrides
Composable component APIs
Variant props from tokens, not arbitrary style overrides
No !important
Fix specificity, don't override it
See design-guide for Sales Hub heading tokens, surface hierarchy, and financial display rules. See design-token-architecture for W3C DTCG format, naming conventions, and CVA patterns.
7. Testing
Rule
Enforcement
Pyramid shape
Many unit, some integration, few E2E
Test behavior, not implementation
Public interfaces and observable outcomes only
Coverage guardrails
70-80% line coverage; focus on logic and edge cases
No dead tests
No test.skip / xit without linked ticket
Co-located test files
.test.ts next to source .ts
Deep reference: references/testing-patterns.md. See craft-doctrine for quality dimensions that define what "tested" means per artifact type.
8. DevOps & CI/CD
Rule
Enforcement
Trunk-based development
Short-lived branches (<2 days); feature flags control visibility
Pipeline as code
Build, lint, typecheck, test, security scan — all automated gates
Feature flag lifecycle
Owner + expiration; remove within 30 days of GA
No force operations
No --force push, no --no-verify, no reset --hard without cause
Rollback strategy
Health checks + documented recovery path
9. AI/LLM Skill & Prompt Design
Rule
Enforcement
RCCF structure
Role, Context, Constraints, Format in every prompt
Structured outputs
JSON schemas or Zod validation; never free-text parsing
Few-shot examples
2-3 examples for non-trivial tasks
Eval coverage
Every skill has evals.json with 7+ scenarios
Explicit scope boundaries
Define what skill does AND does not do
See skill-scaffold for skill creation methodology. See craft-doctrine for skill content quality dimensions.
10. Next.js App Router
Rule
Enforcement
Server Components default
'use client' is opt-in, pushed down the tree
Server Actions = public API
Zod validation + auth check as first two operations
Explicit caching
revalidatePath / revalidateTag after mutations
Loading states
loading.tsx or Suspense boundaries for async routes
No Pages Router patterns
No getServerSideProps, getStaticProps, _app.tsx
Deep reference: references/nextjs-patterns.md. See nextauth-patterns for auth guard choice (requireAuth vs requireOrgAuth vs withOrgAuth) and 13 critical anti-patterns. See middleware-architecture for the request pipeline (CSRF, CSP, onboarding redirect).
Cross-Domain Enforcement Priorities
These rules appear across 3+ domains — highest enforcement weight:
Validate all input server-side (Security + Next.js + Testing)
Never expose secrets or PII (Security + DevOps + GDPR)
Semantic HTML over ARIA hacks (Accessibility + Design System)
Automate quality gates in CI (Code Quality + Testing + DevOps + Security)
Test behavior, not implementation (Testing + Code Quality)
Token hierarchy, never hardcoded values (Design System + Performance)
Server Components by default (Next.js + Performance + Security)
design-guide is the authoritative design system contract
L1 focal point rules, F-pattern layout, zone-based composition
composition-theory
composition-theory owns layout composition rules
Font loading, OpenType features, vertical rhythm
typography
typography owns deep typographic engineering
Token sync contract, APCA contrast math
color-science
color-science owns the color system rules
SCSS architecture, BEM naming, design token integration
scss-expert
scss-expert owns CSS architecture patterns
What "better" means per artifact type
craft-doctrine
craft-doctrine defines quality dimensions and the enrichment principle
1---2name: best-practice3description: 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).4license: MIT5---67# Best Practice — Cross-Cutting Quality Enforcement
89## Domain Context
1011**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.
1213## Coverage
1415Cross-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.
1617## Coverage (14 domains)
1819Code 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).
2021> **Authority:** Cross-domain quality gate. Does not override specialist skills — catches violations that fall between specialist boundaries. Defer to specialists for depth.
22> **Scope:** "Small focused changes" means scope discipline, NOT code reduction. See craft-doctrine for the enrichment principle.
2324## Philosophy
2526This 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.
2728---
2930## Cross-Domain Synergy
31As the baseline enforcement layer, this skill connects:
32- **ui-ux & composition-theory**: Enforcing layout rules (one L1 focal point, F-pattern for data, density-first spacing).
33- **visual-design & design-guide**: Surface hierarchy, card depth, information density vs whitespace balance.
34- **typography & semantics**: Strict adherence to 6-level heading hierarchy, Minor Third scale, readable names.
35- **color-science**: Greyscale chrome enforcement, financial-only semantic color, triple encoding for colorblind safety.
36- **copywriting**: Validating copy inside PRs against the brand's calm-authority tone.
3738## 1. Code Quality
3940| Rule | Enforcement |
41|------|-------------|
42| Strict TypeScript | `"strict": true`, no `any`, no `@ts-ignore` without explanation |
43| SOLID principles | One responsibility per module, depend on abstractions |
44| DRY / KISS / YAGNI | No duplicate blocks >10 lines, no premature abstraction |
45| Explicit return types | Every exported function declares its return type |
46| Small focused changes | PRs touch one logical concern, <400 changed lines (excl. generated) |
4748> Anti-patterns and checklist: `references/code-quality-checklist.md`. See semantics for naming rules, craft-doctrine for quality dimensions.
4950## 2. Documentation
5152| Rule | Enforcement |
53|------|-------------|
54| Self-documenting names | If a name needs a comment, rename it |
55| Comments explain WHY | Code explains what; comments explain intent, gotchas, business rules |
56| ADRs for decisions | `/sales-hub/docs/adr/` — Context, Decision, Alternatives, Consequences |
57| TSDoc on public APIs | `@param`, `@returns`, `@throws` on exported functions |
58| No stale TODOs | Every `// TODO` must reference a ticket: `// TODO(SH-1234)` |
5960> See adr for ADR creation methodology. See doc-updater for the documentation update protocol.
6162## 3. Security (OWASP Top 10:2025)
6364| Priority | Rule | Check |
65|----------|------|-------|
66| A01 | Broken Access Control | Every endpoint verifies auth AND authz; default-deny |
67| A03 | Supply Chain | No high/critical CVEs; pin dependency versions |
68| A05 | Injection | Parameterized queries only; Zod validation on all input |
69| A10 | Exception Handling | No stack traces to clients; all errors caught server-side |
70| — | Secret management | No secrets in source; `.env*` in `.gitignore` |
7172> Deep reference: `references/security-checklist.md`. See security-scanning for SQL injection prevention, CSRF, and webhook security details. See gdpr-compliance for PII masking, per-provider erasure handlers, and retention enforcement.
7374## 4. Accessibility (WCAG 2.2)
7576| Rule | Standard | Check |
77|------|----------|-------|
78| Semantic HTML first | WCAG 4.1.2 | `<button>` not `<div onClick>`, native `<dialog>`, `<nav>` |
79| Keyboard operable | WCAG 2.1.1 | All functionality via Tab/Enter/Space/Arrows; no traps |
80| Color contrast | WCAG 1.4.3 | 4.5:1 text, 3:1 UI components |
81| Target size | WCAG 2.5.8 | 24px WCAG minimum; **Sales Hub enforces 44x44px** |
82| Heading hierarchy | WCAG 1.3.1 | Sequential h1>h2>h3, no skipping, one h1 per page |
8384> Deep reference: `references/accessibility-checklist.md`. See a11y for Sales Hub 44px targets, Axe-Core Playwright tests, focus-ring system, reduced-motion strategy, and live-region placement.
8586## 5. Performance
8788| Rule | Threshold | Check |
89|------|-----------|-------|
90| LCP | <2.5s | No lazy-load on above-fold images |
91| INP | <200ms | No main-thread tasks >50ms; defer non-critical JS |
92| CLS | <0.1 | Images have `width`/`height`; no layout shifts |
93| Bundle discipline | Monitor in CI | Dynamic `import()` for routes; no full-library imports |
94| Image optimization | AVIF/WebP | `next/image` with proper sizing; `loading="lazy"` below fold |
9596> Deep reference: `references/performance-checklist.md`. See react-best-practices for 57 detailed performance optimization rules across 8 categories.
9798## 6. Design System
99100| Rule | Enforcement |
101|------|-------------|
102| Three-tier token hierarchy | Primitive > Semantic > Component; never use primitives in components |
103| No hardcoded values | All colors, spacing, typography via tokens — never raw hex or px |
104| Dark mode via CSS custom properties | `:root` light, `[data-theme="dark"]` overrides |
105| Composable component APIs | Variant props from tokens, not arbitrary style overrides |
106| No `!important` | Fix specificity, don't override it |
107108> See design-guide for Sales Hub heading tokens, surface hierarchy, and financial display rules. See design-token-architecture for W3C DTCG format, naming conventions, and CVA patterns.
109110## 7. Testing
111112| Rule | Enforcement |
113|------|-------------|
114| Pyramid shape | Many unit, some integration, few E2E |
115| Test behavior, not implementation | Public interfaces and observable outcomes only |
116| Coverage guardrails | 70-80% line coverage; focus on logic and edge cases |
117| No dead tests | No `test.skip` / `xit` without linked ticket |
118| Co-located test files | `.test.ts` next to source `.ts` |
119120> Deep reference: `references/testing-patterns.md`. See craft-doctrine for quality dimensions that define what "tested" means per artifact type.
121122## 8. DevOps & CI/CD
123124| Rule | Enforcement |
125|------|-------------|
126| Trunk-based development | Short-lived branches (<2 days); feature flags control visibility |
127| Pipeline as code | Build, lint, typecheck, test, security scan — all automated gates |
128| Feature flag lifecycle | Owner + expiration; remove within 30 days of GA |
129| No force operations | No `--force` push, no `--no-verify`, no `reset --hard` without cause |
130| Rollback strategy | Health checks + documented recovery path |
131132## 9. AI/LLM Skill & Prompt Design
133134| Rule | Enforcement |
135|------|-------------|
136| RCCF structure | Role, Context, Constraints, Format in every prompt |
137| Structured outputs | JSON schemas or Zod validation; never free-text parsing |
138| Few-shot examples | 2-3 examples for non-trivial tasks |
139| Eval coverage | Every skill has evals.json with 7+ scenarios |
140| Explicit scope boundaries | Define what skill does AND does not do |
141142> See skill-scaffold for skill creation methodology. See craft-doctrine for skill content quality dimensions.
143144## 10. Next.js App Router
145146| Rule | Enforcement |
147|------|-------------|
148| Server Components default | `'use client'` is opt-in, pushed down the tree |
149| Server Actions = public API | Zod validation + auth check as first two operations |
150| Explicit caching | `revalidatePath` / `revalidateTag` after mutations |
151| Loading states | `loading.tsx` or Suspense boundaries for async routes |
152| No Pages Router patterns | No `getServerSideProps`, `getStaticProps`, `_app.tsx` |
153154> Deep reference: `references/nextjs-patterns.md`. See nextauth-patterns for auth guard choice (requireAuth vs requireOrgAuth vs withOrgAuth) and 13 critical anti-patterns. See middleware-architecture for the request pipeline (CSRF, CSP, onboarding redirect).
155156---
157158## Cross-Domain Enforcement Priorities
159160These rules appear across 3+ domains — **highest enforcement weight**:
1611621. **Validate all input server-side** (Security + Next.js + Testing)
1632. **Never expose secrets or PII** (Security + DevOps + GDPR)
1643. **Semantic HTML over ARIA hacks** (Accessibility + Design System)
1654. **Automate quality gates in CI** (Code Quality + Testing + DevOps + Security)
1665. **Test behavior, not implementation** (Testing + Code Quality)
1676. **Token hierarchy, never hardcoded values** (Design System + Performance)
1687. **Server Components by default** (Next.js + Performance + Security)
1698. **Small, focused changes** (Code Quality + DevOps + AI/LLM)
1709. **Explicit caching strategy** (Next.js + Performance)
17110. **Structure over verbosity** (AI/LLM + Documentation)
172173---
174175## Verification
176177- [ ] **Code:** No `any`, no lint suppressions without reason, explicit return types
178- [ ] **Docs:** Names are self-documenting, TODOs have tickets, ADRs for decisions
179- [ ] **Security:** Auth checked, input validated, no secrets in source
180- [ ] **A11y:** Semantic HTML, keyboard operable, contrast passing, targets 44px (Sales Hub)
181- [ ] **Perf:** No unnecessary client JS, images optimized, no layout shifts
182- [ ] **Design:** All values from tokens, no `!important`, dark mode works
183- [ ] **Tests:** New logic has tests, behavior-focused, no dead tests
184- [ ] **DevOps:** No force operations, feature flags have owners, pipeline passes
185- [ ] **AI/LLM:** Skills have evals, prompts have structure, scope is bounded
186- [ ] **Next.js:** Server Components default, Server Actions secured, caching explicit
187188## Do NOT Use When
189190| Instead of this skill | Use | Why |
191|---|---|---|
192| Deep code review methodology (feedback phrasing, review structure) | `code-review` | code-review owns the review process and feedback format |
193| Auth guard function selection (requireAuth vs requireOrgAuth) | `nextauth-patterns` | nextauth-patterns owns the auth boundary decision tree |
194| SQL injection prevention, CSRF, webhook signature verification | `security-scanning` | security-scanning owns automated security scanning depth |
195| PII masking, per-provider erasure handlers, retention enforcement | `gdpr-compliance` | gdpr-compliance owns GDPR-specific implementation |
196| 44px touch targets, focus-ring system, reduced-motion strategy | `a11y` | a11y owns Sales Hub accessibility implementation depth |
197| Financial calculation correctness (rounding, decimal precision) | `code-logic` | code-logic owns financial semantics and calculation rules |
198| Heading tokens, surface hierarchy, financial display rules | `design-guide` | design-guide is the authoritative design system contract |
199| L1 focal point rules, F-pattern layout, zone-based composition | `composition-theory` | composition-theory owns layout composition rules |
200| Font loading, OpenType features, vertical rhythm | `typography` | typography owns deep typographic engineering |
201| Token sync contract, APCA contrast math | `color-science` | color-science owns the color system rules |
202| SCSS architecture, BEM naming, design token integration | `scss-expert` | scss-expert owns CSS architecture patterns |
203| What "better" means per artifact type | `craft-doctrine` | craft-doctrine defines quality dimensions and the enrichment principle |
Run npx skillmds@latest add aibot88/best-practice in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
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). It is listed under Web & Frontend on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: CAUTION, Skill Scanner: PASS. Capability flags: reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.
aibot88 (@aibot88) published this skill. Their other Agent Skills are listed on their SkillMD profile.
aibot88