Anti-Patterns

These patterns are sourced verbatim from the Vandoko design direction document (DESIGN.md) and split into two tiers: deterministic checks that tooling can flag automatically, and subjective checks that require LLM-as-judge evaluation.

Programmatic Anti-Patterns

These are deterministic — the visual-quality-gate skill flags them mechanically with no ambiguity.

1. Repeated "left copy / right artifact" layout

Using the same left-text / right-artifact composition on more than two sections per page creates a mechanical cadence that signals templated output rather than deliberate design.

Rule: flag when this layout appears more than twice on a single page.

Example violation:

// Section 1 — left copy / right artifact
<section className="grid grid-cols-2">
  <div>{/* copy */}</div>
  <div>{/* artifact */}</div>
</section>

// Section 2 — same
<section className="grid grid-cols-2">
  <div>{/* copy */}</div>
  <div>{/* artifact */}</div>
</section>

// Section 3 — same (FLAGGED: > 2 occurrences)
<section className="grid grid-cols-2">
  <div>{/* copy */}</div>
  <div>{/* artifact */}</div>
</section>

Fix: alternate with stacked, full-width, or centered layouts to give each section one distinct visual register.

2. Card-in-card depth greater than 1

Nesting a card inside another card creates competing surfaces and visual noise. Dense nested panels compete for the same visual priority and collapse the depth system.

Rule: flag any card component rendered as a direct child of another card component.

Example violation:

<Card>
  <Card> {/* FLAGGED: card-in-card */}
    <p>Nested content</p>
  </Card>
</Card>

Fix: flatten to a single surface. Use border, background tint, or spacing to create visual separation without nesting card primitives.

3. Hex colors in component code

Raw hex values in JSX or CSS bypass the design token system. They cannot respond to dark mode, cannot be updated globally, and signal one-off decisions rather than a coherent system.

Rule: flag any #[0-9a-fA-F]{3,6} literal in .tsx, .ts, .jsx, .css component files. Exception: Canvas 2D contexts where CSS variables are not resolvable at runtime.

Example violation:

// FLAGGED: raw hex in className string or style prop
<div style={{ color: "#55EEDD" }}>…</div>
<div className="text-[#55EEDD]">…</div>

Fix: use design tokens via CSS custom properties:

<div className="text-cyan-400">…</div>
// or
<div style={{ color: "var(--color-cyan)" }}>…</div>

4. Generic 4-up Lucide icon-card grid

A 2×2 or 4-across grid of icon + heading + one-liner cards is the most common AI-generated service layout. It makes Vandoko feel interchangeable with any generic agency site and provides no proof of capability.

Rule: flag any grid with exactly 4 identical card structures, each containing a Lucide icon, a heading, and a short paragraph, with no other content differentiation.

Example violation:

<div className="grid grid-cols-4 gap-6">
  {services.map((s) => (
    <Card key={s.id}>
      <LucideIcon name={s.icon} /> {/* FLAGGED: generic icon-card grid */}
      <h3>{s.title}</h3>
      <p>{s.description}</p>
    </Card>
  ))}
</div>

Fix: replace with an outcome stack — each row connects visitor pressure, Vandoko build, and business shift. Differentiate card content with proof artifacts (consoles, metrics, screenshots) rather than icons.

5. Fake KPI dashboard without data-source attribute

Metrics and dashboards that do not prove a business claim erode trust. A number without provenance is decoration, not proof.

Rule: flag any element that renders a numeric KPI, stat, or metric inside a dashboard or card component unless it carries a data-source attribute pointing to a concrete reference.

Example violation:

// FLAGGED: metric with no data-source
<StatCard label="Leads generated" value="4,200" />

Fix:

<StatCard
  label="Leads generated"
  value="4,200"
  data-source="Vandoko ABM pilot — Q1 2025 — client: [name on file]"
/>

If a metric cannot be sourced, it must be removed or replaced with a qualitative proof artifact.

Subjective Anti-Patterns

These require LLM-as-judge evaluation. They cannot be caught mechanically because they depend on reading intent and composition holistically.

Multiple dominant jobs in one section

Each page section must have a single dominant job: pressure, move, proof, shift, or next action (see Section Grammar below). A section that tries to establish context, present a service, show proof, and prompt action simultaneously fails all of them.

Signal to check: count the primary verbs and outcomes in a section. If a reviewer cannot name one dominant job in five seconds, the section is doing too much.

Cyan as decoration rather than system signal

Cyan (#55EEDD / --color-cyan) is reserved for system signal and action in the Vandoko visual system — CTAs, active states, interactive indicators. Using it as a decorative color (borders, text highlights, background tints) without functional meaning dilutes its signal value.

Signal to check: does every cyan element in the section correspond to an interactive or attention-directing function? Decorative cyan that does not direct action is flagged as "uncertain" or below by the evaluator.

Halo-effect read of first viewport scoring "uncertain" or below

The first viewport controls the visitor's prior for everything that follows. If a reviewer reading only the first 100vh cannot quickly form a confident positive impression of what Vandoko does and for whom, the page fails its primary job regardless of how strong the lower sections are.

Signal to check: ask an evaluator to describe Vandoko's value proposition after seeing only the first viewport. A response of "uncertain" or below indicates the hero has failed the halo-effect test.

Why This Matters

These patterns are grounded in two governing constraints from the Vandoko design direction:

Section Grammar (Pressure → Move → Proof → Shift → Next): Every reusable section must carry all five beats. Anti-patterns like multiple dominant jobs or unanchored metrics break one or more beats, leaving the visitor without the context or confidence needed to take the next action.

Obsidian / charcoal / cyan restraint: The visual system uses a narrow palette deliberately. Cyan carries meaning (signal, action). Obsidian and charcoal carry weight (surface, structure). Decorative color use outside these roles collapses the system's ability to communicate hierarchy at a glance.

Removing these patterns is not cosmetic polish — it is the difference between a page that converts and one that reads as competent-but-generic.

Enforcement

These checks are enforced by the visual-quality-gate skill, part of the qa-orchestrator in the marketing-website-qa tool-bag plugin.

• The qa-orchestrator skill routes visual quality checks to visual-quality-gate and aggregates results into a QualityReport with a 0–100 score.
• The visual-quality-gate skill audits 8 visual dimensions and produces specific, implementable fix instructions with exact file locations and Tailwind class changes.
• Pass threshold for visual quality: score ≥ 70.

To run a visual quality audit:

Trigger: "check visual quality" or "run visual quality gate"
Plugin: marketing-website-qa (tool-bag)
Skill: qa-orchestrator → visual-quality-gate

The programmatic anti-patterns listed above correspond directly to checks run by visual-quality-gate. The subjective anti-patterns are evaluated as part of the LLM-as-judge pass within the same skill.