Audit code consistency

Code Consistency Audit

Static Websites on cPanel

Inconsistent code is the most common byproduct of AI-assisted development. When a site is built across multiple sessions, by multiple agents, or iteratively over time, patterns drift. Selectors that worked one way become exceptions. Functions get duplicated with slight variations. CSS variables get hardcoded when someone is in a hurry. This audit finds all of it.

The goal is not aesthetic perfection — it is that any developer (or agent) reading any file in the project can immediately understand the system, predict where things live, and extend it without introducing new inconsistencies.

---

Core Principles Applied

Every finding in this audit traces back to one of these principles:

• DRY — Don't Repeat Yourself: Every piece of knowledge must have a single, unambiguous representation. Duplicated rules create divergence when one copy gets updated and the others don't.
• KISS — Keep It Simple: The simplest solution that works is the correct solution. Overly complex selectors, deeply nested functions, and unnecessary abstractions reduce maintainability.
• YAGNI — You Aren't Gonna Need It: Unused code is a liability. Unused CSS classes, unreferenced JS functions, and commented-out blocks add noise.
• Boy Scout Rule: Leave the code cleaner than you found it. When an inconsistency is found, fix it — don't just flag it.
• Single Responsibility: Each function does one thing. Each CSS file covers one responsibility. Each component handles one concern.

---

Severity Levels

Level	Description	Action
Critical	Breaks the system or causes conflicts that affect functionality	Fix immediately
High	Creates maintainability problems that will compound over time	Fix before launch
Medium	Inconsistency that reduces readability and predictability	Fix within current sprint
Low	Minor style deviation with minimal practical impact	Fix when convenient

---

Section 1 — CSS Architecture

1.1 CSS Variables — The Absolute Rule

Every value that belongs to the design system must live in variables.css and be consumed through var() everywhere else.

What to check — scan all CSS files for hardcoded values that should be variables:

/* ❌ Hardcoded — will drift from the system */
.card {
  background-color: #0D0D14;
  font-family: 'DM Sans', sans-serif;
  border-radius: 12px;
  transition: opacity 200ms ease;
}

/* ✅ System-compliant */
.card {
  background-color: var(--bg-surface);
  font-family: var(--font-sans);
  border-radius: var(--radius-md);
  transition: opacity var(--transition-normal);
}

Flag every instance of: hex colors outside variables.css, font family strings, hardcoded spacing values matching the scale, transition durations, border radius values.

1.2 CSS File Organization

Verify the file structure is respected:

• variables.css — only custom properties, nothing else
• base.css — only reset, body, typography globals, no component styles
• components.css — only reusable components
• animations.css — only keyframes and transition definitions
• [page].css — only styles specific to that page, no globals

Flag: component styles inside base.css, page-specific styles inside components.css, variables declared outside variables.css, duplicate declarations across files.

1.3 Class Naming — BEM Consistency

The entire project must use BEM throughout:

/* ✅ Consistent BEM */
.card { }
.card__title { }
.card__description { }
.card--featured { }

/* ❌ Mixed conventions in the same project */
.card-title { }        /* kebab without BEM */
.cardTitle { }         /* camelCase */
.card_title { }        /* snake_case */
.card.featured { }     /* modifier as separate class */

Flag: classes using camelCase/snake_case/PascalCase, modifiers as separate classes instead of BEM --, elements without BEM __, inconsistent hyphen usage for modifiers.

1.4 Property Order

CSS property order must be consistent across all rules:

.component {
  /* 1. Positioning */
  position: relative;
  z-index: 1;

  /* 2. Box model */
  display: flex;
  width: 100%;
  padding: var(--space-6);

  /* 3. Visual */
  background-color: var(--bg-surface);
  border: 1px solid var(--border-default);
  border-radius: var(--radius-md);

  /* 4. Typography */
  font-family: var(--font-sans);
  font-size: 1rem;
  color: var(--text-primary);

  /* 5. Transitions */
  transition: border-color var(--transition-normal);
}

Flag rules where typography appears before box model, or transitions in the middle of visual properties.

1.5 Specificity and !important

What to check:

• Any !important declarations — each one is a specificity problem patched instead of solved
• Selectors with more than 3 levels of nesting (nav ul li a span)
• ID selectors (#element) used for styling instead of classes
• Inline styles in HTML that should be in CSS

/* ❌ Specificity problems */
#hero .card .card__title span { color: red !important; }

/* ✅ Flat, specific, no !important needed */
.hero-card__title { color: var(--text-primary); }

1.6 Duplicate Rules

What to check:

• Same selector defined more than once across all CSS files
• Groups of properties appearing identically in multiple selectors — extract to shared class
• Media queries overriding the same properties multiple times

---

Section 2 — JavaScript Quality

Full code examples for all JS patterns: see references/javascript-patterns.md

2.1 Naming Conventions

Every identifier must follow established conventions without exception:

Element	Convention	Example
Constants	UPPER_SNAKE_CASE	const MAX_RETRIES = 3;
Variables	camelCase	const chatContainer = ...;
Functions	verb + noun, camelCase	function showTypingIndicator() {}
Booleans	question form	isActive, hasLoaded, canSubmit

Flag: single-letter variables outside loop counters, abbreviations requiring mental decoding (btn, el, tmp), functions without a verb, booleans not in question form, constants in camelCase.

2.2 Function Size and Responsibility

Each function must do exactly one thing. Functions longer than 20 lines signal that something may be doing too much. A function that validates, sends, updates DOM, and handles errors should be split into single-responsibility functions.

Full before/after refactoring example: see references/javascript-patterns.md

2.3 Guard Clauses — Flat Over Nested

Deep nesting is a readability problem. Guard clauses eliminate nesting by returning early:

/* ❌ Deep nesting */
async function sendMessage(message) {
  if (message) {
    if (message.length > 0) {
      if (!isLoading) {
        // actual logic — buried 3 levels deep
      }
    }
  }
}

/* ✅ Guard clauses — flat and readable */
async function sendMessage(message) {
  if (!message || message.length === 0) return;
  if (isLoading) return;

  // actual logic — immediately visible
}

Flag: functions with more than 2 levels of nesting, if blocks wrapping the entire function body, nested if/else chains convertible to guard clauses.

2.4 Constants Over Magic Values

Flag: hardcoded strings used more than once, hardcoded numbers with no obvious meaning, URLs/IDs/class names written inline, configuration values not extracted to named constants.

/* ❌ Magic values */
setTimeout(() => { }, 200);
if (message.length > 500) { }

/* ✅ Named constants */
const TYPING_ANIMATION_DELAY_MS = 200;
const MAX_MESSAGE_LENGTH = 500;

2.5 Error Handling

What to check:

• All fetch calls wrapped in try/catch
• Catch blocks doing something meaningful — not just console.log(error) with no user feedback
• No silent failures — errors caught and swallowed without action
• Consistent pattern for showing error states to the user
• response.ok checked before parsing

2.6 Dead Code

What to check:

• Functions defined but never called
• Variables declared but never used
• Commented-out blocks of old code — delete it, git preserves history
• console.log statements left from development
• Event listeners on elements that no longer exist

2.7 Duplication

What to check:

• Same DOM query written more than once — cache it in a variable
• Same logic copy-pasted in multiple handlers — extract to a function
• Multiple functions doing almost the same thing — consolidate with a parameter

---

Section 3 — HTML Consistency

3.1 Structural Patterns

What to check:

• Same component type uses same HTML structure across all pages
• Heading levels consistent across pages — <h2> for section titles everywhere, not mixed
• Class names applied consistently for the same component

3.2 Attribute Order

Attributes should follow a consistent order across all elements:

  Contáctanos

3.3 Formatting

What to check:

• Indentation consistent throughout — 2 spaces or 4, never mixed
• Attributes on same line for short elements, broken to multiple lines for long ones — consistently
• All required closing tags present
• Self-closing tags consistent — <img> vs <img />, pick one

3.4 Inline Styles

What to check:

• No style="" attributes in HTML (except dynamically set via JS)
• No <style> blocks inside HTML files — all styles belong in CSS file structure

---

Section 4 — Cross-File Consistency

4.1 File Reading Order (Newspaper Metaphor)

Each file should read top-to-bottom from general to specific:

CSS files: Variables → resets → layout → components → modifiers → states → media queries

JavaScript files: Constants → DOM references → main functions → helper functions → event listeners

Flag: helper functions before the main functions that use them, event listeners scattered instead of grouped at bottom, constants defined inline instead of at top.

4.2 Comment Quality

Comments should explain WHY — not WHAT. If a comment explains what the code does, the code should be rewritten to be self-explanatory.

/* ❌ Explains what — the code already says this */
// Get the chat container element
const chatContainer = document.getElementById('chat-container');

/* ✅ Explains why — context the code cannot provide */
// Delay before showing response to feel more natural — immediate
// response feels robotic and breaks the conversational experience
setTimeout(() => showResponse(data), RESPONSE_DELAY_MS);

// N8N webhook requires snake_case keys — camelCase returns 400
const payload = { user_question: message, session_id: sessionId };

Flag: comments restating what code already says, commented-out code blocks, // TODO without date or owner, console.log with // debug or // remove later.

4.3 Consistency Between Pages

What to check:

• Every HTML page has the same <head> structure and CSS files in the same order
• Navbar HTML identical across all pages — no drift
• Footer HTML identical across all pages
• Same utility classes used consistently — no page-specific reinventions

---

Section 5 — Self-Check Before Completing

Before declaring this audit complete, verify:

Check	Question
✅ All CSS files reviewed	Were variables.css, base.css, components.css, animations.css, and all page CSS files checked?
✅ All JS files reviewed	Were all JavaScript files checked for naming, structure, and duplication?
✅ All HTML files reviewed	Were all pages checked for structural consistency?
✅ Cross-file patterns	Were inconsistencies between files identified, not just within them?
✅ Dead code removed	Were unused classes, functions, and variables deleted — not just flagged?
✅ Boy Scout applied	Is the code cleaner now than before the audit started?

---

Audit Output Format

Code Consistency Audit — [Project Name]
Date: [Date]
Summary

Critical issues: X
High priority: X
Medium priority: X
Low priority: X
Files reviewed: X
Overall consistency assessment: [Consistent / Needs work / Fragmented]

Critical Issues
[Issue title]

File: [filename.css / filename.js / filename.html]
Line: [line number if applicable]
Principle violated: [DRY / KISS / YAGNI / Single Responsibility]
Issue: [What is wrong]
Fix: [Specific correction with code example]

High Priority
[Same format]
Medium Priority
[Same format]
Low Priority
[Same format]
Patterns Found (recurring issues)
[List issues that appear in multiple files — systemic problems
that should be fixed with a find-and-replace approach]
Recommended Fix Order

[First because it affects the most files...]
[Then...]
[Finally...]

Full quick-reference checklist: see references/checklist.md