Rules and recipes
for building pages.

1. 01

   Use BaseLayoutAA

   Every new page imports ../layouts/BaseLayoutAA.astro. It loads HeaderAA, FooterAA, the utility bar, Plus Jakarta Sans, and the variant-d.css palette. Never use BaseLayout, BaseLayoutA, BaseLayoutC, or BaseLayoutD for new pages — they're older variants kept around for parity with experimental builds.

2. 02

   Compose from blessed sections

   New page = pick from src/components/sections-aa/ + src/components/sections-d/. Don't build new sections from scratch unless the existing ones genuinely don't fit. When in doubt, fork an existing component into sections-aa/ with a new name.

3. 03

   One H1 per page

   The H1 is the page-level headline. Every other heading is H2/H3. The H1 lives in the hero section and includes the page's primary keyword.

4. 04

   Every H2 carries the keyword

   Target keyword on the homepage is 3PL for ecommerce brands. Each H2 must surface "3PL" + "ecommerce brands" or close variants. See section 06 for the production-bound H2 list.

5. 05

   Color is rationed

   Teal #1d9890 is precious — eyebrows, icons, divider rules, accents on dark only. Body text is --d-text (#4a5568). Headings are always navy-900 (#0a1d3f) on light, white on dark navy.

6. 06

   Use the existing component patterns

   Cards = white on white, ring-1 ring-d-line, 20px radius, soft shadow. Eyebrow + H2 + lede header pattern repeats across every section. Don't invent new card shapes.

7. 07

   Generate icons, don't hunt them

   New icon needed? Use the prompt template in section 07 to generate one via nano-banana-pro at 1:1 aspect, model: pro. Save to /public/icons/<set>/. Never use Heroicons / Phosphor / generic icon libraries — they read off-brand next to our generated set.

CTA language

Voice

Generated icons

Solid teal pictograms representing a category. Use ON cards (next to title), in numbered lists, in primary visual slots.

/public/icons/<set>/

Real brand logos

Client + integration logos in full color. Use in trust strips, integration grids, testimonial attribution. Never modify (no greyscale, no recolor).

/public/clients/, /public/logos/

Brand patterns

Abstract logistics line illustrations. Use as ambient section backgrounds at 0.06–0.18 opacity. Always with fade-mask to white. Never on cards.

/public/images/generated/

Decision tree

Generation prompts

Use Gemini (nano-banana-pro). Set model: pro.

Solid color flat brand icon for "[concept]".
[Subject description].
Rendered in pure solid teal #1d9890 only.
Clean white square background.
No gradients, no shadows, no outlines.
Bold geometric shape, fills 60–70% of canvas.
Modern app icon set style.

Subtle abstract logistics line illustration
for "[section]".
Thin line-art elements at low contrast:
dotted route paths, package boxes, location
pins, truck silhouettes, supply-chain diagrams.
Flat 2D, no fills — line work only.
Stroke: pale blue-gray (#c2d0e6), 1px lines.
Composed as ambient texture, not foreground.
White background.

• Teal/colored gradient overlays on dark cards

  Reads SaaS-template. The pricing card ships solid navy-950 with no overlays.

• Identical 4-column symmetric grids stacked back-to-back

  Vary composition: split, asymmetric, full-width.

• Vertical hairline dividers between cells in logo strips

  Read tabular. The trust strip uses gap-only.

• Grayscale logo bands with hover-color reveal

  Cold for our positioning. Logos render in full color.

• One-word orphan lines in H2s

  Fix with shorter copy or restructure the <span class="block"> breaks.

• Single brand logo on a category card

  Implies single-platform support. Use a generated category icon.

• Mismatched icon weights (line-art SVG next to real brand logo)

  All icons in a section must come from the same family.

• "Either B2C or B2B"-style false dichotomies

  Most 3PLs do support both. Use real D2C pain points instead.

• "Get a Custom Quote" copy anywhere

  Replaced by "Contact Sales" in May 2026.

• Heroicons / Phosphor / generic icon libraries

  Generate the icon you need via nano-banana-pro instead.

• Decorative SVG noise / floating particles / wavy dividers

  No.

• Multiple brand patterns in one section

  One pattern per section, max.

src/
  pages/
    home-aa.astro          ← production-bound homepage
    brand.astro            ← this design system
    [new-page].astro       ← new pages go here
  layouts/
    BaseLayoutAA.astro     ← USE THIS for new pages
  components/
    sections-aa/           ← production sections (HeroAA, ServicesAA, etc.)
    sections-d/            ← shared sections still in use (StatsD, TestimonialsD, FAQD)
    ui/                    ← Container, Section, etc. primitives
  data/
    services-h.ts          ← 12 search-driven services
    site.ts                ← brand metadata, nav, finalCTA
  styles/
    variant-d.css          ← color tokens + base type scale (READ-ONLY)
    global.css             ← reset + utilities

public/
  icons/
    services-aa/           ← 4 generated service icons (teal pictograms)
    why-vertex-aa/         ← 6 generated WhyVertex icons
    [new-set]/             ← new icon sets go here
  images/generated/        ← 10 brand patterns (section backgrounds)
  clients/                 ← 8 real Vertex client logos
  logos/                   ← integration platform + carrier logos
  flags/                   ← country flag SVGs
  video/                   ← hero video (hero-720.mp4 / .webm)