# gaipack Patterns — Page & Section Patterns

> **Source of Truth**
>
> - **This file is the source of truth for:**
>   - **Page patterns** (home / service detail / service hub / listings / articles / case studies / landing pages / forms / system states)
>   - **Section patterns** (hero / problems / solutions / process steps / case studies / related services / closing CTA / FAQ)
>   - The component combination each pattern uses
>   - Layout structure (ASCII / required class sequences)
>   - Pattern-specific mandatory rules and prohibitions
> - **This file refers to:**
>   - Visual specification (colors, typography, spacing, glow) → `DESIGN.md`
>   - Component props / code examples / technology-specific prohibitions → `COMPONENTS.md`
>   - The AI working protocol and self-audit → `AGENTS.md`
>
> **Update frequency:** Medium (when a new page or section kind is needed). No heavy brand-owner approval; a light approval from the implementation team is enough.

This document templates the **page and section structures that recur across the gaipack site**. It is the source of consistency between pages.

---

## Reading order

The reading order for AI implementation follows `AGENTS.md §1` (requirements → PATTERNS.md → COMPONENTS.md → DESIGN.md). Existing pages are consulted only after the pattern and its components are settled, and only as a reference for props and data wiring.

---

## Contents

1. [Shared layout](#shared-layout)
2. [Pattern 1: Home page](#1-home-page)
3. [Pattern 2: Service detail page](#2-service-detail-page)
4. [Pattern 3: Service hub page](#3-service-hub-page)
5. [Pattern 4: Listing page (news / blog / gallery / case studies)](#4-listing-page)
6. [Pattern 5: Article page (blog / news)](#5-article-page)
7. [Pattern 6: Case-study page](#6-case-study-page)
8. [Pattern 7: Landing page (LP)](#7-landing-page-lp)
9. [Pattern 8: Form page](#8-form-page)
10. [Pattern 9: System states (loading / error / 404)](#9-system-states)
11. [Section patterns](#section-patterns)
12. [Choosing a pattern](#choosing-a-pattern)
13. [Supplementary references](#supplementary-references)

---

## Shared layout

Every page renders inside the root layout (`app/layout.tsx`). Pages never render the header or footer themselves.

### Page shell

```
┌────────────────────────────────────────────────┐
│  Header (fixed, translucent, tri-color line)   │  ← COMPONENTS.md §2.1
├────────────────────────────────────────────────┤
│                                                │
│  <main>  page body (stacked sections)          │
│    ├─ Hero (pt-26 clears the fixed header)     │
│    ├─ Section × N (py-24 – py-32)              │
│    └─ Closing CTA                              │
│                                                │
├────────────────────────────────────────────────┤
│  Follow Us (social accounts)                   │  ← COMPONENTS.md §1.5.9
├────────────────────────────────────────────────┤
│  Footer (5 columns)                            │  ← COMPONENTS.md §2.2
└────────────────────────────────────────────────┘
```

### Required class sequences

- **Section shell:** `<section className="py-32 px-4 relative overflow-hidden">` (dense sections use `py-24`)
- **Container:** `<div className="container mx-auto max-w-7xl relative z-10">`; card grids add `max-w-6xl mx-auto` inside
- **Hero top padding:** `pt-26 pb-20` to clear the fixed header (`min-h-[80vh]` fills the viewport)
- **Background texture:** one grid overlay per section, `absolute inset-0 opacity-[0.095]` + `backgroundImage` (`DESIGN.md §2.4`)
- **Theming:** base classes are dark, `light:` overrides light (`DESIGN.md §1`, absolute principle 3)

### Absolute rules

- ❌ Never re-place `<Header>` / `<Footer>` inside a page (the root layout outputs them once)
- ❌ Never output a second `<main>` inside a page
- ❌ Never add raw hex for section backgrounds (use `var(--surface)` / `var(--surface-raised)` / `var(--svc-panel)`)
- ❌ Never cause horizontal page scroll (tables, diagrams, and code scroll inside their own `overflow-x-auto` container)
- ❌ Never add a dark-only section (no merge without `light:` overrides)

---

## 1. Home page

**Purpose:** The home page (`/`) conveys the brand world and the full picture of the 20 services on one page.

### Components used

| Role | Component |
| --- | --- |
| Hero CTAs | `<CTA variant="primary" size="large">` + `<CTA variant="secondary" size="large">` |
| Service cards | `ServiceCard` from `features/services` |
| Case-study cards | `Link` + `ImageWithFallback` (16:9) |
| Social | `<SocialMediaSection>` |

### Structure (13 fixed sections)

```
[Header]
 1. Hero            Headline「AIで、ビジネスを加速させる。」+ sub-copy + 2 CTAs
                    + 20-service icon grid (5×4 on desktop / two marquee rows on mobile) + scroll indicator
 2. Value Proposition   Three key metrics (values from the source of truth only)
 3. Process         AIDD process overview + video + 4 steps (要件定義 → 設計 → 実装 → 運用)
 4. AIDD Showcase   Banner to the external demo gallery
 5. Services        How / Base / What card grid
 6. Related LPs     Carousel linking to the three landing pages
 7. Trust           Certifications, awards, and track-record badges
 8. Case Studies    Two-column highlight cards + link to the listing
 9. News / Blog / Partner / Recruit   Latest news, blog ranking, partner program, recruiting
10. Closing CTA     Full-width call to action
11. Follow Us
12. Footer
```

### Rules

- **Primary actions appear only in the hero and the closing CTA.** Intermediate sections use `secondary` / `tertiary`
- **Metric values match the source of truth (service definitions); notes and disclaimers go in the footer**
- **The 20-service grid is generated from `serviceCatalog`**, never hand-listed
- **Adding or removing a section requires brand-owner confirmation** (the home page is the face of the brand)

### Prohibitions

- ❌ "Helpfully" adding sections that are not in the requirements (KPI cards, announcement bars …)
- ❌ Rendering the hero headline as an image (text + gradient text only)

### Why

- Showing all 20 services first makes "one-stop" tangible, then trust (track record, certifications) and specifics (case studies, process) are stacked in order. Reordering breaks the narrative.

---

## 2. Service detail page

**Purpose:** Each of the 20 service pages (`/services/[service]`) walks from problems → solution → process → case studies → related services → CTA. AIDD services nest under the hub `/services/aidd`.

### Components used

| Role | Component |
| --- | --- |
| Breadcrumb | `<Breadcrumb items={buildServiceBreadcrumbItems(slug)} />` |
| Hero CTA | `<CTA variant="primary" size="large" href="/contact">` |
| Visual | `<img>` (`/images/services/<slug>.png`) or `<LiteYouTubeEmbed>` |
| Problem cards | Card with a top accent line + `lucide-react` icon at `w-12` |
| Case-study cards | `Link` + `<ImageWithFallback>` |
| Related services | `Link` cards with a top accent line |
| Social | `<SocialMediaSection>` |

### Structure (10 blocks)

```
[Hero]              Breadcrumb / category tag (How・Base・What) / H1 (gradient text) / lead
                    / one sentence naming the audience and outcome / metric card / CTA / visual in the right column
[Problems]          「こんな課題、ありませんか？」 three-column cards
[Solutions]         Heading + numbered solution blocks × 2–3 (text left, typographic visual right, alternating)
                    + an optional wide supporting card
[Service-specific]  Comparison tables / pricing / phases / interactive demos / live previews (optional)
[Process]           4 steps (numbered circles + connector lines)
[FAQ]               Accordion (optional)
[Case studies]      Two-column cards (optional)
[Related services]  Stacked wide cards × 2–3
[Closing CTA]       「まずはお気軽にご相談ください」
[Follow Us]
```

### Rules

- **Hero metrics use only source-of-truth values.** Keep qualifiers such as「最大」「目指す」exactly as the source states them
- **Immediately after the lead, one sentence names the audience and the outcome** (for AI search and summarization)
- **Three problems and four process steps** (comparability across pages)
- **Numbered solutions alternate sides** (1: text left, 2: text right, 3: text left)
- **Case-study cards only reference published cases in `docs/cases`**; company names follow the disclosure scope of the case page
- **Related services are 2–3 services from the same category or adjacent phases**

### Prohibitions

- ❌ Numbers, guarantees, or definitive superiority claims that are not in the source of truth
- ❌ Adding a primary CTA to an intermediate section
- ❌ Problem cards in any count other than 3 (4+ is overload, 2 is thin)

### Why

- Twenty pages sharing one skeleton let users find the same information in the same place on any service. Page-specific creativity stays inside the "service-specific" block.

---

## 3. Service hub page

**Purpose:** The service listing (`/services`) and the AIDD hub (`/services/aidd`) give a category-level overview.

### Structure

```
[Hero]              H1 + lead (no CTA, or lead only)
[Category × 3]      How (AI 駆動開発) / Base (AI 活用基盤) / What (AI 活用プロダクト)
                    a service-card grid under each category
[AIDD hub only]     Before / After table, the four AIDD pillars, service-per-phase mapping
[Closing CTA]
```

### Rules

- **Category badge colors and order (How / Base / What) are fixed**
- **Service descriptions come from `SERVICE_DESCRIPTIONS` in `serviceCatalog`** (never rewritten per page)
- **Breadcrumbs keep the hierarchy `HOME > サービス一覧 > AIDD`**

---

## 4. Listing page

**Purpose:** Listings for news (`/news`), blog (`/blog`), gallery (`/gallery`), and case studies (`/column`), including category, author, and paginated variants.

### Components used

| Role | Component |
| --- | --- |
| Breadcrumb | `<Breadcrumb>` |
| Category / author filter | A row of pill tags (`Link`) |
| Listing card | `Link` + `<ImageWithFallback>` (16:9) + date + category + title |
| Pagination | `<Pagination currentPage totalPages basePath>` |
| RSS | `<RssLink href="/news/feed.xml">` |
| Loading | `loading.tsx` with `<HeroLoadingShell>` + `<Skeleton>` |

### Structure

```
[Hero]              BreadcrumbWithJsonLd / H1 with a short accent underline / lead / RssLink
[Filters]           Category (news, blog) and author (blog) pill rows; the current one is filled
[Listing panel]     <div className="bg-black/40 light:bg-surface-card backdrop-blur-sm rounded-xl border border-white/10 light:border-border-subtle p-4 md:p-6">
                    card grid inside (three columns on desktop, one on mobile)
                    empty state: "該当する … がありません" centered with py-16 in the same panel
[Sidebar (blog)]    popular posts / popular authors ranking (rendered only when ranking data is enabled)
[Pagination]        <Pagination> — page 2 onward is `${basePath}/page/${n}`
[Closing CTA] (optional)
```

### Rules

- **URL design is fixed: pagination at `/page/[n]`, categories at `/category/[slug]`**
- **Items per page and sort order follow the domain API definition** (never changed in the UI)
- **Zero results show an empty-state message plus a path back to the top of the listing** (Pattern 9)
- **Dates use a `time` element formatted `YYYY/M/D`**

### Prohibitions

- ❌ Hand-rolled pagination (use `<Pagination>`)
- ❌ Wrapping listing cards in the shadcn `<Card>` (double frame)
- ❌ Adding a search bar to a listing (blog search is a dedicated client-side UI only)

---

## 5. Article page

**Purpose:** Blog posts (`/blog/[slug]`) and news details (`/news/[slug]`).

### Components used

| Role | Component |
| --- | --- |
| Breadcrumb | `<BreadcrumbWithJsonLd>` (emits structured data too) |
| Body | Markdown renderer (headings, tables, code, Mermaid diagrams) |
| Share | `<ShareButtons url title label>` |
| Ask AI | `<AskAI question referenceUrls>` (blog only) |
| Structured data | `<JsonLd data>` |

### Structure

```
[Hero]              Breadcrumb / category and date / H1 / author (blog) / thumbnail (16:9)
[Body]              single column at max-w-3xl; headings h2 → h3; tables and diagrams scroll with overflow-x-auto
[Article end]       ShareButtons / "copy page" (Markdown URL) / AskAI
[Related]           three cards from the same category (optional)
[Closing CTA]
```

### Rules

- **Body width is `max-w-3xl` (768px).** Only figures and tables may widen to `max-w-5xl`
- **Mermaid diagrams are theme-aware** (dark: neon brand colors, light: deep colors)
- **Body headings start at h2** (h1 is the title only)
- **External links open in a new tab with the `sr-only` note**

### Prohibitions

- ❌ CTA buttons inside the body (only the closing CTA at the end)
- ❌ Writing the company name as「アイレット」alone in an article

---

## 6. Case-study page

**Purpose:** Customer case studies (`/column/case-study-*`), built as static pages.

### Structure

```
[Hero]              pt-24 pb-12, bottom border accent at 10%
                    Breadcrumb / case tag / H1 (text-4xl md:text-5xl lg:text-6xl, gradient span, the key number in accent) / customer and industry (per disclosure scope) / main visual
[Summary]           py-12 on surface-black (light: surface); three-column grid (md:grid-cols-3 gap-6) — problem / solution / result
[Body sections]     py-12 each, alternating surface-black and the black → #0A0A0A gradient (light: surface)
                    H2 at text-3xl md:text-4xl; two-column grids (md:grid-cols-2 gap-8) for before / after and approach details
[Closing]           py-24 on surface-black; H2「AI で、ビジネスを加速させる」at text-5xl md:text-6xl font-bold + CTA primary large
```

### Rules

- **Customer names and logos appear only within the permission scope of the case page.** When other pages cite a case, omit the company name and link to the case page
- **Result figures keep qualifiers such as「約」「最大」exactly as the source states them**
- **The main visual is 16:9 inside a card**
- **Case-study pages sit on `surface-black`, not `surface`** — the only page family that uses pure black. Keep the `light:bg-surface` overrides on every section

---

## 7. Landing page (LP)

**Purpose:** Campaign or single-service pages (`/lp/*`): `/lp/aidd-camp` / `/lp/governance` / `/lp/platform-engineering`.

### Structure

```
[Header (shared)]
[Hero]              LP-specific staging (3D graph, diagrams, video)
[Pitch blocks × N]  LP-specific sections colored with scoped tokens (--lp-* / --gov-* …)
[Pricing / plans]   Only the price tiers in the source of truth; tax-exclusive stated explicitly
[FAQ]
[Closing CTA]
[Footer (shared)]
```

### Rules

- **Use the shared header and footer** (no exceptions for LPs)
- **LP-specific colors are defined as scoped tokens (`--lp-*` / `--gov-*`) with both dark and light values**
- **LP-specific keyframes are prefixed (`pf*` / `gp*` / `camp*`)**
- **`/lp/aidd-camp` is a static LP without theming (the only exception).** Every other LP must support both themes
- **An LP whose canonical URL is a service page (aidd-camp) points `canonical` to that service page**

### Prohibitions

- ❌ Adding or changing global tokens for an LP (keep them scoped)
- ❌ Building an LP-specific header

---

## 8. Form page

**Purpose:** Contact (`/contact`), an embedded external form (HubSpot).

### Structure

```
[Hero]              Breadcrumb / H1 / lead
[Form]              embedded form on a card surface; Skeleton while loading
[Notes]             response hours, link to the privacy policy
```

### Rules

- **The form's own look follows the embed's constraints; only the shell (card, spacing) is styled with tokens**
- **Post-submit navigation and completion display follow the embed** (no custom completion screen)

---

## 9. System states

**Purpose:** States outside the normal flow: loading, errors, 404, forbidden.

### Variants

| State | File | Component | Main path back |
| --- | --- | --- | --- |
| Loading | `loading.tsx` | `<HeroLoadingShell>` + `<Skeleton>` | — |
| Runtime error | `error.tsx` | `<ErrorState error reset title backHref>` | Retry / back to listing |
| 404 | `not-found.tsx` | heading + description + CTA | Back to home |
| Forbidden | `forbidden.tsx` | heading + description | Back to home |
| Empty (0 items) | inside listings | message + path | Listing top / clear category |

### Structure

```
<main className="relative z-10 flex-1 flex flex-col items-center justify-center text-center px-4 pt-32 pb-20 md:pt-40 md:pb-28">
  <p className="text-[8rem] md:text-[12rem] font-bold leading-none tracking-tight bg-linear-to-r from-accent-blue via-[#009FAC] to-[#C64AD4] bg-clip-text text-transparent select-none">404</p>
  <h1 className="text-2xl md:text-4xl font-semibold text-content mt-2 mb-4">Page Not Found</h1>
  <p className="text-content-muted text-base md:text-lg max-w-md mx-auto mb-10 leading-relaxed">お探しのページは存在しないか、移動した可能性があります。</p>
  <CTA variant="primary" size="large" href="/">ホームに戻る</CTA>
</main>
```

The status code is rendered as a giant Trinity-gradient number with three blurred light orbs behind it; the page renders `<Header>` and `<Footer>` itself because it sits outside the route layouts. The 404 and forbidden pages are the one place where a `primary large` CTA appears outside a hero or closing section — the page has no other action.

### Mandatory rules

- **State is expressed with icon + heading + description** (never color alone)
- **At least one path back** (no dead ends)
- **Header and footer stay in place** (never take over the whole screen)
- **Skeletons match the real content's dimensions** and fade in after a 200ms delay (flicker prevention)

### Prohibitions

- ❌ Showing stack traces or internal details to users
- ❌ Reporting errors with a toast only

---

## Section patterns

Section templates shared by service detail pages and the home page. **When adopting one, keep the structure and change only copy and item counts.**

### S-1 Hero (service detail)

```
<section className="relative min-h-[80vh] flex items-center justify-center px-4 overflow-hidden pt-26 pb-20">
  grid overlay / two vertical circuit lines / two light orbs (blur-3xl)
  <div className="container mx-auto max-w-7xl relative z-10">
    <Breadcrumb className="mb-4" />
    <div className="grid lg:grid-cols-2 gap-12 lg:gap-16 items-center">
      left:  category tag → H1 (gradient text) → lead → audience sentence → metric card → CTA
      right: visual (lg+; on mobile it appears above the CTA)
    </div>
  </div>
</section>
```

### S-2 Problems (「こんな課題、ありませんか？」)

- Major H2 + a 48px accent line (`h-px w-48 mx-auto`)
- Three-column cards (`max-w-6xl`); each card has a 1px top accent line at 45% + `w-12` icon + H3 + body

### S-3 Solutions (numbered blocks)

- Section heading + lead (`max-w-3xl`)
- Blocks are spaced with `space-y-32`; each block is `grid lg:grid-cols-2 gap-16 items-center`
- Text side: number badge (`w-10 h-10 rounded-lg bg-accent-cyan/10 border-accent-cyan/30`) + minor H2 + body + checklist (`CheckCircle2 w-5 h-5 text-accent-cyan`)
- Visual side: a typographic visual (an `aspect-video` card with large Latin text and tags)

### S-4 Process (4 steps)

- `grid md:grid-cols-4 gap-8 max-w-6xl`
- Each step: numbered circle (`w-16 h-16 rounded-full border-2 border-[#2E3C49]/70 light:border-border-subtle/70`) + H3 (two lines) + body
- Connector lines between steps (`absolute top-8 … h-px bg-accent-cyan/35`, md+ only)

### S-5 Case studies

- Major H2 + lead + two-column cards (`Link`, 16:9 image, case tag, date, H3, excerpt,「詳しく見る」)
- Hover: border turns cyan, outer glow, image scales slightly

### S-6 Related services

- Stacked wide cards (`p-8 md:p-10`, top accent line, a `w-16 h-16` icon box on the left, H3 + body +「詳細を見る」)

### S-7 Closing CTA

- A `max-w-5xl` box with `2xl` radius (`p-12 md:p-16`, 32px grid overlay, an 8% radial glow at the bottom)
- "Contact Us" pill → major H2「まずはお気軽にご相談ください」→ body (`max-w-2xl`) → `CTA primary large`

### S-8 FAQ (accordion)

- `<Accordion type="single" collapsible>`; questions in `font-medium`, answers at body size; dividers in `border-subtle`

---

## Choosing a pattern

| Requirement | Pattern |
| --- | --- |
| Present the brand and every service | Pattern 1 Home |
| Explain one service and lead to contact | Pattern 2 Service detail |
| Overview several services by category | Pattern 3 Service hub |
| List many items by time or category | Pattern 4 Listing |
| Let the reader read one article or announcement | Pattern 5 Article |
| Tell a customer's results as a story | Pattern 6 Case study |
| A campaign or single pitch needing bespoke staging | Pattern 7 LP |
| Accept input | Pattern 8 Form |
| Communicate a state outside the normal flow | Pattern 9 System state |

When in doubt, do not implement — follow `AGENTS.md §3 Stop process`. **A new page kind gets a pattern in this file before it is implemented** (adding one later leaves exceptions behind).

---

## Supplementary references

General usability principles (eye-tracking, F-pattern scanning, Hick's law …) may be consulted as support but never override this file or `DESIGN.md`. On conflict, the norm priority in `AGENTS.md §2` wins.

---

## Related documents

- Visual tokens and brand principles → `DESIGN.md`
- Component props / code examples / technology-specific prohibitions → `COMPONENTS.md`
- AI working protocol (stop process, norm priority, self-audit) → `AGENTS.md`
- Change history → `CHANGELOG.md`
- Live examples → https://www.gaipack.ai/ (the real thing for every pattern)