DEV Community: Odilon HUGONNOT

PicoCSS vs Bootstrap vs Tailwind: choosing your CSS framework

Odilon HUGONNOT — Tue, 19 May 2026 09:00:03 +0000

The project: TOUSPOURRIS.COM, a satirical site tracking French political corruption. The UI had to mimic the aesthetic of French Republic institutions — bleu france #000091, red #e1000f, Marianne typography. An immediately recognizable design, deliberately official for the ironic effect. This isn't a modern SaaS with rounded cards and gradients. It's an institutional pastiche.

And that aesthetic choice dictated the CSS framework choice. When the design is precise and identity-driven, the framework is no longer a neutral accelerator — it can become an obstacle. I evaluated the three usual suspects: Bootstrap, Tailwind, PicoCSS. Here's why two were ruled out and the third won.

The problem with Bootstrap

Bootstrap imposes its components. Buttons with border-radius: 0.375rem, colors in variables but an entire color system to override, navbar with preconfigured behaviors. For a generic design — admin dashboard, SaaS landing page — it's perfect: the defaults are the right ones.

For a French Republic institutional design, it's the opposite. You spend your time undoing what Bootstrap did. !important everywhere, CSS variables rewritten. You end up with Bootstrap-0 — Bootstrap stripped of its defaults — carrying 50 kB of CSS you don't use. The cost/benefit ratio flips: Bootstrap becomes a liability, not an asset.

The problem with Tailwind

Tailwind solves the over-opinionatedness problem by having no components. But it shifts the problem: for a consistent design, you need to configure the design system in tailwind.config.js — RF colors, Marianne typography — then apply utility classes everywhere in the HTML. That's work.

And for this Symfony project with Twig templates, it meant learning an additional tool, a Node.js build step in a PHP stack, for a result that native CSS can deliver directly. The effort/benefit ratio didn't justify introducing Tailwind into a context where the design system was already defined and documented by the French government.

Why PicoCSS

PicoCSS starts from a different philosophy: clean styles on semantic HTML elements, without classes. A <button> is styled. An <input> is styled. A <nav> is styled. The base is usable immediately without writing a single line of CSS. And most importantly: the defaults are minimal and easy to override with CSS custom properties.

/* Override the PicoCSS design system with RF colors */
:root {
    --pico-primary: #000091;          /* Bleu France */
    --pico-primary-hover: #1212ff;
    --pico-del-color: #e1000f;        /* RF Red */
    --pico-font-family: 'Marianne', system-ui, sans-serif;
    --pico-border-radius: 0;          /* Institutional = no rounding */
}

5 CSS variables and the site looks like a government portal. No !important, no specificity war with the framework. PicoCSS doesn't resist — it yields cleanly because it was designed to do exactly that.

The RF design system in practice

The French government's visual identity is open source — the DSFR design system. Colors, typography, spacing, all defined and documented. With PicoCSS as the base:

Marianne font (downloadable from the official DSFR) loaded via @font-face
CSS variables for --bleu-france, --rouge-marianne, --gris-cool
Custom components — "corruption gauge" badge, politician cards — written in native CSS, no utility classes

The result: a site that deliberately looks like an official portal. The satirical effect relies entirely on the design. A visitor who arrives without context sees an institutional interface before realizing it's satire. That disconnect only works if the design is credible — and it wouldn't have been with off-the-shelf Bootstrap or hastily configured Tailwind.

When to choose what

There's no universal framework. Concrete criteria for deciding:

Situation

Recommended framework

Admin dashboard, generic SaaS

Bootstrap or shadcn/ui

Lots of utilities, custom design via config

Tailwind

Precise design, semantic HTML, solid native CSS skills

PicoCSS

Project < 10 pages, CSS < 500 lines

No framework

The real question isn't "which framework is best" but "what am I going to fight against". Bootstrap imposes its components. Tailwind imposes its classes. PicoCSS imposes almost nothing — which can be an advantage or a disadvantage depending on whether you want to build or to override.

Conclusion

PicoCSS isn't the universal answer. It's the answer when you have a precise design and you don't want to spend your time undoing a framework's decisions. For TOUSPOURRIS.COM, it was the right choice: a coherent institutional design in ~300 lines of custom CSS, without any specificity war.

The code is readable by any developer without knowing the conventions of a specific framework. In 2 years, if someone picks up the project, they read CSS — not Bootstrap or Tailwind. It's a form of technical restraint that has a short-term cost (no ready-made components) and a long-term benefit (no dependencies to maintain, no version migrations to manage).

Vue.js SPA SEO: how I made my app invisible to Google (and how I fixed it)

Odilon HUGONNOT — Mon, 18 May 2026 09:00:03 +0000

I spent three months building CitoyenNote — a Vue.js 3 + Vite SPA. Clean code, Composition API, composables for everything, Pinia for state management. The kind of codebase you're actually proud of. Then I typed the site name into Google and got back a single result: the homepage. With a title of "Document". No description. And none of the 80+ municipality pages were indexed.

That's the SPA SEO problem in a nutshell. Here's what I learned fixing it.

What Google actually sees in a SPA

A classic server-rendered page serves complete HTML on the first request. Google's crawler receives a full <head> with a title, meta description, canonical URL — everything it needs to index the page.

A Vue.js SPA in CSR mode serves this on every URL:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Document</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/assets/index-Bx9kLmQp.js"></script>
  </body>
</html>

Google's crawler does execute JavaScript — but with significant caveats: it uses an older Chromium version, JS rendering is deferred and lower priority than HTML crawling, and there's no guarantee of complete execution on every page. Relying on JS execution for SEO is a gamble. The fix is to give Google correct HTML right from the start.

The full solution requires six steps.

Step 1: get the index.html basics right

The static index.html at the root of your Vite project is the baseline every page will fall back to when JavaScript hasn't run yet. It should be respectable:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />

    <title>CitoyenNote — Citizen reviews of French municipalities</title>
    <meta name="description" content="Read and share ratings and reviews about your municipality: safety, schools, public transport, urban planning. Unfiltered citizen feedback." />

    <!-- Open Graph -->
    <meta property="og:type" content="website" />
    <meta property="og:title" content="CitoyenNote — Citizen reviews of French municipalities" />
    <meta property="og:description" content="Read and share ratings and reviews about your municipality: safety, schools, public transport, urban planning." />
    <meta property="og:url" content="https://citoyennote.fr/" />
    <meta property="og:image" content="https://citoyennote.fr/og-image.jpg" />
    <meta property="og:locale" content="en_US" />

    <!-- Twitter Card -->
    <meta name="twitter:card" content="summary_large_image" />
    <meta name="twitter:title" content="CitoyenNote — Citizen reviews of French municipalities" />
    <meta name="twitter:description" content="Read and share ratings and reviews about your municipality." />
    <meta name="twitter:image" content="https://citoyennote.fr/og-image.jpg" />

    <link rel="canonical" href="https://citoyennote.fr/" />
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

This static fallback is what social media crawlers (Twitter, LinkedIn, Slack) will read when sharing your homepage — they rarely execute JavaScript.

Step 2: @unhead/vue for dynamic meta tags

For every route to have its own title and meta description, you need a library that manipulates the <head> reactively as the route changes. The current standard for Vue 3 is @unhead/vue, which replaces the older vue-meta.

Installation

npm install @unhead/vue

Setup in main.ts

import { createApp } from 'vue'
import { createHead } from '@unhead/vue'
import App from './App.vue'
import router from './router'

const app = createApp(App)
const head = createHead()

app.use(router)
app.use(head)
app.mount('#app')

Usage in a component

The simplest approach: call useHead() in each page component, with computed values that react to async data loading.

// views/MunicipalityView.vue
<script setup lang="ts">
import { computed } from 'vue'
import { useHead } from '@unhead/vue'
import { useMunicipality } from '@/composables/useMunicipality'

const props = defineProps<{ slug: string }>()
const { municipality, loading } = useMunicipality(props.slug)

useHead({
  title: computed(() =>
    municipality.value
      ? `${municipality.value.name} — CitoyenNote`
      : 'Loading... — CitoyenNote'
  ),
  meta: [
    {
      name: 'description',
      content: computed(() =>
        municipality.value
          ? `Citizen reviews of ${municipality.value.name} (${municipality.value.department}): overall score ${municipality.value.score}/10, ${municipality.value.reviewCount} reviews.`
          : 'Municipality reviews on CitoyenNote.'
      ),
    },
    {
      property: 'og:title',
      content: computed(() =>
        municipality.value ? `${municipality.value.name} — CitoyenNote` : 'CitoyenNote'
      ),
    },
    {
      property: 'og:description',
      content: computed(() =>
        municipality.value
          ? `Citizen reviews of ${municipality.value.name}: overall score ${municipality.value.score}/10.`
          : ''
      ),
    },
    {
      property: 'og:url',
      content: computed(() =>
        `https://citoyennote.fr/municipality/${props.slug}`
      ),
    },
    {
      property: 'og:type',
      content: 'article',
    },
  ],
  link: [
    {
      rel: 'canonical',
      href: computed(() => `https://citoyennote.fr/municipality/${props.slug}`),
    },
  ],
})
</script>

The key point: the values are computed(), so they update automatically when municipality.value is populated after the API call. No need to manually call anything when data arrives.

Extract into a composable

If you have many page types, avoid duplicating useHead() calls. Extract into a typed composable:

// composables/useMunicipalitySeo.ts
import { computed, type Ref } from 'vue'
import { useHead } from '@unhead/vue'
import type { Municipality } from '@/types'

export function useMunicipalitySeo(
  municipality: Ref<Municipality | null>,
  slug: string
) {
  useHead({
    title: computed(() =>
      municipality.value
        ? `${municipality.value.name} — CitoyenNote`
        : 'CitoyenNote'
    ),
    meta: [
      {
        name: 'description',
        content: computed(() =>
          municipality.value
            ? `Citizen reviews of ${municipality.value.name}: score ${municipality.value.score}/10, ${municipality.value.reviewCount} reviews.`
            : ''
        ),
      },
      {
        property: 'og:title',
        content: computed(() =>
          municipality.value ? `${municipality.value.name} — CitoyenNote` : 'CitoyenNote'
        ),
      },
      {
        property: 'og:url',
        content: `https://citoyennote.fr/municipality/${slug}`,
      },
    ],
    link: [{ rel: 'canonical', href: `https://citoyennote.fr/municipality/${slug}` }],
  })
}

Usage in the component becomes a single line:

useMunicipalitySeo(municipality, props.slug)

Step 3: robots.txt

Place a robots.txt at the root of your public/ folder — Vite will copy it as-is to the build output:

User-agent: *
Allow: /

Sitemap: https://citoyennote.fr/sitemap.xml

If parts of your app shouldn't be indexed (admin panels, user dashboards, private routes), block them explicitly:

User-agent: *
Disallow: /admin/
Disallow: /dashboard/
Disallow: /settings/
Allow: /

Sitemap: https://citoyennote.fr/sitemap.xml

Step 4: dynamic sitemap

A static sitemap only covers routes you know at build time. For a content-heavy app with thousands of municipality pages, the sitemap must be generated dynamically from the database.

In CitoyenNote's case, the backend is a Go API (Echo framework). I added a dedicated /sitemap.xml route:

// routes/sitemap.go
package routes

import (
    "encoding/xml"
    "net/http"
    "time"

    "github.com/labstack/echo/v4"
    "citoyennote/internal/repository"
)

type URLSet struct {
    XMLName xml.Name `xml:"urlset"`
    Xmlns   string   `xml:"xmlns,attr"`
    URLs    []URL    `xml:"url"`
}

type URL struct {
    Loc        string  `xml:"loc"`
    LastMod    string  `xml:"lastmod,omitempty"`
    ChangeFreq string  `xml:"changefreq,omitempty"`
    Priority   float64 `xml:"priority,omitempty"`
}

func SitemapHandler(repo repository.MunicipalityRepository) echo.HandlerFunc {
    return func(c echo.Context) error {
        municipalities, err := repo.ListAll(c.Request().Context())
        if err != nil {
            return err
        }

        urlset := URLSet{
            Xmlns: "http://www.sitemaps.org/schemas/sitemap/0.9",
        }

        // Static routes
        urlset.URLs = append(urlset.URLs,
            URL{Loc: "https://citoyennote.fr/", Priority: 1.0, ChangeFreq: "daily"},
            URL{Loc: "https://citoyennote.fr/search", Priority: 0.8, ChangeFreq: "weekly"},
        )

        // Dynamic municipality pages
        for _, m := range municipalities {
            urlset.URLs = append(urlset.URLs, URL{
                Loc:        "https://citoyennote.fr/municipality/" + m.Slug,
                LastMod:    m.UpdatedAt.Format(time.DateOnly),
                ChangeFreq: "weekly",
                Priority:   0.7,
            })
        }

        c.Response().Header().Set("Content-Type", "application/xml; charset=UTF-8")
        return xml.NewEncoder(c.Response()).Encode(urlset)
    }
}

No build step, no caching needed for this size. For a site with 100,000+ pages, consider splitting into a sitemap index and multiple sub-sitemaps (Google's limit is 50,000 URLs per sitemap file).

Submit the sitemap URL in Google Search Console and verify it parses correctly.

Step 5: JSON-LD structured data

JSON-LD is Google's preferred format for Schema.org structured data. It goes in a <script type="application/ld+json"> tag in the <head>. @unhead/vue handles this cleanly:

// Add to useMunicipalitySeo.ts
useHead({
  // ... existing title/meta config ...
  script: [
    {
      type: 'application/ld+json',
      innerHTML: computed(() => {
        if (!municipality.value) return ''

        return JSON.stringify({
          '@context': 'https://schema.org',
          '@type': 'Place',
          name: municipality.value.name,
          description: `Citizen reviews of ${municipality.value.name}.`,
          url: `https://citoyennote.fr/municipality/${slug}`,
          aggregateRating: {
            '@type': 'AggregateRating',
            ratingValue: municipality.value.score,
            reviewCount: municipality.value.reviewCount,
            bestRating: 10,
            worstRating: 0,
          },
        })
      }),
    },
  ],
})

The AggregateRating type is what enables star ratings to appear directly in Google search results (rich snippets). Not guaranteed, but Google does pick it up reliably for well-structured pages with enough reviews.

For a blog or article, use @type: "BlogPosting" with datePublished, dateModified, and author. For a product, use @type: "Product". The Google structured data gallery lists all types that qualify for rich results.

Step 6: the 404 route

A SPA with client-side routing needs a server-level fallback. Without it, directly navigating to /municipality/paris returns a real 404 from the server before Vue even loads. Google interprets that as a 404 and won't index the page.

The fix depends on your hosting. On Apache:

# .htaccess at the root of your SPA
<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /

  # Don't rewrite real files and directories
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d

  # Everything else goes to index.html
  RewriteRule ^ index.html [L]
</IfModule>

On Nginx:

location / {
    try_files $uri $uri/ /index.html;
}

On Vite's dev server, this works automatically. On production, it's on you.

Inside Vue Router, add a catch-all route that returns a proper 404 UI — and critically, set the HTTP status code. With SSR or prerendering this is straightforward. With pure CSR, the HTTP response for a non-existent route is always 200 (the server returns index.html). Google handles this gracefully for most cases, but it's worth knowing.

// router/index.ts
const routes = [
  // ... your routes ...
  {
    path: '/:pathMatch(.*)*',
    name: 'NotFound',
    component: () => import('@/views/NotFoundView.vue'),
  },
]

The honest limitation: CSR vs SSR

All of the above makes a CSR SPA considerably more Google-friendly. But there's a ceiling.

Google's crawler does execute JavaScript, but it does so in a second wave, hours or days after the initial crawl. The initial crawl reads raw HTML. So what Google sees first is your static index.html — the same fallback on every URL — with no route-specific content.

If your site depends on search visibility for hundreds or thousands of distinct pages (municipality pages, product pages, article pages), you have two real options:

SSR (Server-Side Rendering): Nuxt 3 for Vue.js. The server renders the full HTML for each request. Google gets the right HTML immediately. The cost: a Node.js server, more complex infrastructure, hydration to manage.
SSG (Static Site Generation): Nuxt or VitePress can pre-render all routes at build time to static HTML files. Perfect for content that doesn't change per-user. The cost: dynamic content (user-specific data, real-time scores) needs hydration after the static shell loads.

For CitoyenNote, I stayed with CSR + the fixes above because the content (municipality scores, reviews) changes frequently and Google does eventually index the JavaScript-rendered pages correctly. The SEO improvement from the fixes was significant: 80+ pages indexed within two weeks of the sitemap submission, versus zero before.

If I were starting again from scratch on a project where SEO is the primary acquisition channel, I'd go with Nuxt 3 from day one.

SEO checklist for Vue.js SPAs

A summary you can run through before launching:

index.html: complete <head> with charset, viewport, default title, meta description, Open Graph tags, Twitter Card, canonical URL
@unhead/vue: installed, registered in main.ts, useHead() called in every page component with computed reactive values
Canonical URLs: set on every page, including the homepage
robots.txt: present in public/, includes Sitemap: directive
Sitemap: all indexable URLs listed, dynamic pages included, submitted to Google Search Console
JSON-LD: relevant schema type on key pages (Place, Product, BlogPosting, Organization...)
Server fallback: .htaccess or Nginx config routes all paths to index.html
404 route: catch-all route defined in Vue Router
Google Search Console: sitemap submitted, URL inspection run on a sample of key pages, coverage report checked after 2 weeks
Social sharing test: Facebook Debugger and Twitter Card Validator on at least 3 URLs (homepage, a content page, a 404)

None of this is particularly complicated. The painful part is discovering three months into a project that you forgot to do it. The checklist exists so you don't have to rediscover it the hard way.

Vue 2 vs Vue 3 and Composition API vs Options API: complete comparison

Odilon HUGONNOT — Sun, 17 May 2026 09:00:02 +0000

Vue 3 launched in late 2020. Five years later, Vue 2 has been officially end-of-life since December 2023, yet migration is still dragging in many projects. Between the reactivity rewrite, the Composition API that throws people off at first, and Vite replacing webpack — there's plenty of reason to stall. Here's what actually changed, what it means for your code, and how to choose between the two APIs.

Vue 2 vs Vue 3: what changed in practice

The reactivity system

This is the deepest change. Vue 2 uses Object.defineProperty to observe mutations — with its well-known limitations: no detection of dynamically added properties, no detection on array indexes. Hence the Vue.set() and this.$set() calls that clutter Vue 2 code.

Vue 3 uses ES2015 Proxy. The entire object is intercepted, not property by property. No more $set, direct mutations are detected natively:

// Vue 2 — adding a reactive property after creation
this.$set(this.user, 'email', 'odilon@example.com') // required

// Vue 3 — works directly
this.user.email = 'odilon@example.com' // reactive automatically

Performance and bundle size

Vue 3 is tree-shakable. Unused features (Transition, KeepAlive, Teleport...) are not included in the final bundle if they aren't imported. Vue 2 included the full runtime regardless.

In practice on an average project: runtime bundle reduced by roughly 40% with Vue 3 vs Vue 2. The reactive diff is also faster thanks to a rewritten virtual DOM patching strategy (static template analysis at compile time).

TypeScript

Vue 2 had a patched-together TypeScript support via vue-class-component and decorators. Functional, but tedious. Vue 3 was rewritten in TypeScript from scratch — types are native, inference works without any special configuration in components.

Fragments, Teleport, Suspense

Three structural additions that were missing in Vue 2:

Fragments: a component can return multiple root elements — no more pointless wrapper <div>
Teleport: render HTML into another DOM node (modals, tooltips) without working around CSS with fragile position: fixed hacks
Suspense: handle async component loading states natively

What breaks during migration

The Vue 3 breaking changes that cause the most damage during migration:

$listeners removed — merged into $attrs
$children removed — use ref or provide/inject
filters removed — use methods or computed properties
v-model: the event is now update:modelValue instead of input
Vuex → Pinia (Vuex 5 never shipped)
Vue Router 4 with some API changes

On a large Vue 2 project with lots of filters, $listeners, and Vuex everywhere, migration takes time. The automated migration via @vue/compat helps but doesn't solve everything.

Options API vs Composition API

This is the question that comes up most often when moving to Vue 3. The short answer: both are officially supported, permanently. It's not a replacement but an alternative.

Options API — quick reminder

export default {
  name: 'UserProfile',
  props: {
    userId: String,
  },
  data() {
    return {
      user: null,
      loading: false,
    }
  },
  computed: {
    displayName() {
      return this.user?.name ?? 'Unknown'
    },
  },
  methods: {
    async fetchUser() {
      this.loading = true
      this.user = await api.getUser(this.userId)
      this.loading = false
    },
  },
  mounted() {
    this.fetchUser()
  },
  watch: {
    userId(newId) {
      this.fetchUser()
    },
  },
}

Composition API — same component

import { ref, computed, watch, onMounted } from 'vue'
import { useUserApi } from '@/composables/useUserApi'

export default {
  name: 'UserProfile',
  props: {
    userId: String,
  },
  setup(props) {
    const user = ref(null)
    const loading = ref(false)

    const displayName = computed(() => user.value?.name ?? 'Unknown')

    async function fetchUser() {
      loading.value = true
      user.value = await api.getUser(props.userId)
      loading.value = false
    }

    watch(() => props.userId, fetchUser)
    onMounted(fetchUser)

    return { user, loading, displayName }
  },
}

Or with <script setup> (the recommended syntax in Vue 3):

// <script setup>
import { ref, computed, watch, onMounted } from 'vue'

const props = defineProps({ userId: String })
const user = ref(null)
const loading = ref(false)

const displayName = computed(() => user.value?.name ?? 'Unknown')

async function fetchUser() {
  loading.value = true
  user.value = await api.getUser(props.userId)
  loading.value = false
}

watch(() => props.userId, fetchUser)
onMounted(fetchUser)

Everything declared inside <script setup> is automatically exposed to the template — no more return {}.

Strengths and weaknesses

Options API

Strengths

Rigid and predictable structure — everyone knows where to find data, methods, computed properties
Low learning curve — ideal for onboarding junior devs or devs coming from other frameworks
Very readable on small components — everything is organized by option type
Abundant documentation, examples everywhere on Stack Overflow and legacy projects

Weaknesses

Business logic gets fragmented across data, methods, computed, watch — impossible to keep one "feature" coherent in a single block
Reusing logic between components forces you through mixins — which create naming collisions and make dependencies opaque
Tedious TypeScript: this inside methods doesn't infer well, annotations everywhere
On large components (200+ lines), navigation becomes painful: data is at the top, the method that modifies it is at the bottom, the watcher is somewhere else

Composition API

Strengths

Business logic can be co-located: everything related to fetchUser (state, method, watcher) stays together
Composables cleanly replace mixins: reusable logic is an explicitly imported function, no magic, no collisions
Native TypeScript: ref<User | null>(null), no this, full inference
More effective tree-shaking: only the Vue functions you use are imported

Weaknesses

More verbose on small components — importing ref, computed, onMounted explicitly for 20 lines of logic
The .value on refs is constant friction, a source of bugs (forgetting .value in JS but not in the template)
Without discipline, <script setup> can turn into a grab-bag — structural freedom has a cost if the team doesn't enforce conventions
Less intuitive for someone coming from Vue 2 or React Class Components — the learning curve is real

Direct comparison on concrete cases

Logic reuse: mixins vs composables

This is where the Composition API wins most clearly. A Vue 2 mixin to handle pagination:

// Vue 2 — mixin
export const paginationMixin = {
  data() {
    return {
      page: 1,
      perPage: 10,
      total: 0,
    }
  },
  computed: {
    totalPages() {
      return Math.ceil(this.total / this.perPage)
    },
  },
  methods: {
    nextPage() { this.page++ },
    prevPage() { this.page-- },
  },
}

// Usage — where data.page comes from is not obvious
export default {
  mixins: [paginationMixin],
  // where does this.page come from? mystery for a new dev
}

// Vue 3 — composable
export function usePagination(initialPerPage = 10) {
  const page = ref(1)
  const perPage = ref(initialPerPage)
  const total = ref(0)

  const totalPages = computed(() => Math.ceil(total.value / perPage.value))

  function nextPage() { page.value++ }
  function prevPage() { page.value-- }

  return { page, perPage, total, totalPages, nextPage, prevPage }
}

// Usage — explicit
const { page, total, nextPage } = usePagination(20)
// we know exactly where page comes from

TypeScript: the concrete difference

// Options API with TypeScript — tedious
export default defineComponent({
  data(): { user: User | null; loading: boolean } { // manual annotation
    return { user: null, loading: false }
  },
  methods: {
    async fetchUser(id: string): Promise<void> {
      this.user = await getUser(id) // this isn't always inferred
    },
  },
})

// Composition API — native inference
const user = ref<User | null>(null)
const loading = ref(false) // inferred as ref<boolean>

async function fetchUser(id: string) {
  user.value = await getUser(id) // correctly typed without annotation
}

Conclusion: when to choose which

Options API if:

You're migrating a Vue 2 project and want to minimize change
The team is junior or comes from other MVC frameworks
Components are small and logic isn't reused
You want a framework-enforced structure without the discipline overhead

Composition API if:

You're starting a new Vue 3 project — it's the ecosystem's default choice
You're using TypeScript seriously
You have complex logic to reuse across components
Components are growing — logic co-location becomes a real advantage

What I wish I'd known when starting with Vue 3: both APIs coexist in the same project. A simple form component can stay in Options API while a complex component with 5 composables switches to Composition API. No need to choose once and for all.

On my recent projects, I use the Composition API by default with <script setup> — TypeScript demands it — and composables for everything touching API calls, complex local state management, and DOM interactions (resize observer, intersection observer, etc.). Options API stays for simple presentational components where the rigid structure is an advantage rather than a constraint.

CLAUDE.md for mobile redesign: the context that changes everything

Odilon HUGONNOT — Sat, 16 May 2026 09:00:02 +0000

Ask Claude Code to "make this responsive" without explaining anything. Here's what you get: desktop-first media queries with max-width everywhere, text-align: justify that looks like swiss cheese on an iPhone SE, 32px-tall buttons untappable with a thumb, and no font-size: 16px on inputs — so guaranteed automatic iOS zoom. This isn't incompetence, it's a lack of context. Claude codes with the generic CSS rules it knows, not the mobile-specific rules you have in mind.

The solution: a specialized CLAUDE.md file. Not the project's generic CLAUDE.md, a dedicated file for mobile redesign and CSS design, with precise rules, pitfalls to avoid, and targets to reach. Claude reads it at session startup and applies these rules consistently.

The problem: Claude without mobile context

Claude Code is a generalist tool. It knows CSS, it knows responsive design, but it doesn't know what your priorities are. Does the project target iPhone SE at 375px or tablets at 768px? Does Lighthouse Accessibility need to hit 90? Is dark mode mandatory? Do you prefer BEM or utility-first?

Without this information, Claude produces correct but generic CSS. It will:

Start from desktop and work down (max-width) rather than the reverse
Forget min-width: 0 on flex items — result: mysterious overflows
Leave inputs at 14px — iOS zoom on every tap
Add text-align: justify because "it looks clean"
Ignore prefers-reduced-motion and safe-area-inset
Not test dark mode

Each of these problems takes 10 seconds to fix once detected. The problem is they pile up and you detect them after shipping.

The specialized CLAUDE.md concept

Claude Code automatically reads CLAUDE.md files present in the project — at the root, and in subdirectories if the instruction is in the config. This is the official mechanism for injecting persistent context into a Claude Code session, without having to repeat it in every prompt.

Most projects have a generic CLAUDE.md: project architecture, code conventions, dev commands. The idea here is different: create specialized CLAUDE.md files for specific tasks. A file dedicated to mobile redesign contains exactly what Claude needs for that task — and nothing superfluous.

You can call it CLAUDE-MOBILE.md and reference it from the main CLAUDE.md, or simply drop it temporarily at the root as CLAUDE.md for the duration of the responsive work. Claude Code also supports the .claude/ directory for additional context files — they're loaded in addition to the root CLAUDE.md, not instead of it.

What this MD contains — and why each section

The file is structured in five sections. Each one responds to a specific moment in the work.

Section 1 — Audit workflow. Before writing any CSS, you need to know where to look. This section gives Claude a precise order: first the viewport tag, then input font sizes, then horizontal overflow, then touch targets. This is the order that minimizes time spent debugging problems caused by an upstream oversight. It also includes Lighthouse targets and the "mobile done" checklist — which prevents Claude from declaring the work finished too early.

Section 2 — Mobile testing tools. Playwright scripts for automated screenshots across multiple device profiles — iPhone SE, iPhone 14, Pixel 7, iPad — without leaving the terminal. Variants for dark mode and prefers-reduced-motion. MCP servers (Puppeteer MCP, Playwright MCP) that allow Claude Code to interact directly with a headless browser during the session. And Lighthouse via CLI to audit in JSON or HTML without opening DevTools.

Section 3 — CSS rules. The complete reference of mobile rules with concrete code for each. Not generic docs: ready-to-use snippets with edge cases already handled. The min-width: 0 trap on flex items, coexistence of the manual toggle with prefers-color-scheme, HTML inputmode attributes that complement the CSS for forms — everything that gets lost when working fast.

Section 4 — Generic CSS conventions. Mobile or not, these rules apply to any CSS work: custom properties for theming, BEM for components, focus-visible for keyboard accessibility, modern properties (clamp(), gap, aspect-ratio, logical properties), and the rule on !important. This is what prevents the session's CSS from looking like a patch applied over existing code.

Section 5 — Test checklist. Devices to test, modes (landscape, dark, reduced motion, text zoom), Lighthouse targets by metric, and screen reader testing basics. Claude uses this to know when the task is truly done, not just "passes on my Chrome emulator at 1440px".

How to use it

Three ways, from simplest to cleanest:

Option 1 — Temporary replacement. Rename or save the existing CLAUDE.md, drop this file at the root as CLAUDE.md for the duration of the responsive work. Restore the original when done. Simple, no configuration.

Option 2 — Reference from existing CLAUDE.md. Add a line to the project's CLAUDE.md:

## Mobile context

For all responsive and CSS work:
see CLAUDE-MOBILE.md at the project root.

Claude Code follows references and reads the pointed file.

Option 3 — .claude/ directory. Place the file in .claude/mobile-css.md. Claude Code automatically loads files in this directory in addition to the root CLAUDE.md. Useful if you have multiple specialized contexts (one for mobile, one for tests, one for deployment) and don't want to merge them.

In all cases, the file stacks with the existing context — it doesn't replace already-present instructions.

The complete file

Here is the exact content to copy. This is the raw file, ready to paste.

# CLAUDE.md — Mobile Redesign & CSS Design

> Specialized context for Claude Code. Drop this file at the project root to guide mobile responsive and CSS design work.

---

## Section 1: Mobile redesign workflow

### Initial audit — where to start

Before touching a single line of CSS, do a quick pass in this order:

1. **Viewport tag** — present? `width=device-width, initial-scale=1`? No `user-scalable=no`?
2. **font-size on inputs** — inspect `<input>`, `<textarea>`, `<select>` fields. If < 16px: iOS zoom guaranteed.
3. **Horizontal overflow** — open Chrome DevTools in mobile mode, check if a scrollbar appears at the bottom. Track with `* { outline: 1px solid red; }`.
4. **Touch targets** — tap buttons and nav links in emulation mode. Anything under 44px height needs fixing.
5. **Justified text** — search for `text-align: justify` in CSS. Remove or limit to desktop only.

### Mobile Lighthouse — targets

Run Lighthouse in "Mobile" mode (not Desktop) in DevTools:

| Metric | Target |
|--------|--------|
| Performance | ≥ 80 |
| Accessibility | ≥ 90 |
| Best Practices | ≥ 90 |
| SEO | ≥ 90 |

Priority alerts to fix: tap targets too small, insufficient contrast, missing viewport, inputs without label.

### DevTools device emulation

- Test with profiles: **iPhone SE (375px)**, **iPhone 14 (390px)**, **Pixel 7 (412px)**, **iPad (768px)**
- Enable "Show media queries" to see active breakpoints
- Test in landscape mode
- Simulate "Slow 4G" network to detect performance issues

### Testing on a real device

Emulation doesn't replace real testing. Specific points to check on an actual phone:
- Automatic iOS zoom on inputs (only visible on real device)
- Scroll momentum and bounce zones
- Safe areas (notch, navigation bar)
- Virtual keyboard pushing the layout

### "Mobile done" checklist

- [ ] No unintentional horizontal scroll
- [ ] All interactive elements ≥ 44×44px
- [ ] No input with font-size < 16px
- [ ] Correct viewport meta tag
- [ ] No `text-align: justify` on mobile
- [ ] Body text ≥ 16px, line-height ≥ 1.5
- [ ] Images with `max-width: 100%`
- [ ] Dark mode works (if implemented)
- [ ] Animations respect `prefers-reduced-motion`
- [ ] Lighthouse Accessibility ≥ 90

---

## Section 2: Mobile testing tools — screenshots, emulation, MCP

### Installing test dependencies

```

bash
# Playwright (recommended — multi-browser)
npm init -y
npm install playwright
npx playwright install chromium

# OR Puppeteer (Chromium only)
npm install puppeteer


```

### Automated mobile screenshots

```

javascript
// screenshot-mobile.mjs
import { chromium } from 'playwright';

const devices = [
  { name: 'iPhone SE', width: 375, height: 667, scale: 2 },
  { name: 'iPhone 14', width: 390, height: 844, scale: 3 },
  { name: 'Pixel 7', width: 412, height: 915, scale: 2.625 },
  { name: 'iPad', width: 768, height: 1024, scale: 2 },
];

const url = process.argv[2] || 'http://localhost:8000';

const browser = await chromium.launch();

for (const device of devices) {
  const context = await browser.newContext({
    viewport: { width: device.width, height: device.height },
    deviceScaleFactor: device.scale,
    isMobile: device.width < 768,
    hasTouch: device.width < 768,
  });
  const page = await context.newPage();
  await page.goto(url, { waitUntil: 'networkidle' });
  await page.screenshot({
    path: `screenshot-${device.name.toLowerCase().replace(/\s/g, '-')}.png`,
    fullPage: true,
  });
  console.log(`✓ ${device.name} (${device.width}px)`);
  await context.close();
}

await browser.close();


```

Usage:

```

bash
node screenshot-mobile.mjs http://localhost:8000
# Generates: screenshot-iphone-se.png, screenshot-iphone-14.png, etc.


```

Claude Code can read these screenshots to visually verify rendering.

### Dark mode and reduced motion screenshots

```

javascript
// screenshot-modes.mjs — dark mode and reduced motion variants
import { chromium } from 'playwright';

const url = process.argv[2] || 'http://localhost:8000';
const browser = await chromium.launch();

// Dark mode - iPhone 14
const darkCtx = await browser.newContext({
  viewport: { width: 390, height: 844 },
  deviceScaleFactor: 3,
  isMobile: true,
  hasTouch: true,
  colorScheme: 'dark',
});
const darkPage = await darkCtx.newPage();
await darkPage.goto(url, { waitUntil: 'networkidle' });
await darkPage.screenshot({ path: 'screenshot-dark-mode.png', fullPage: true });
console.log('✓ Dark mode');
await darkCtx.close();

// Reduced motion - iPhone 14
const reducedCtx = await browser.newContext({
  viewport: { width: 390, height: 844 },
  deviceScaleFactor: 3,
  isMobile: true,
  hasTouch: true,
  reducedMotion: 'reduce',
});
const reducedPage = await reducedCtx.newPage();
await reducedPage.goto(url, { waitUntil: 'networkidle' });
await reducedPage.screenshot({ path: 'screenshot-reduced-motion.png', fullPage: true });
console.log('✓ Reduced motion');
await reducedCtx.close();

await browser.close();


```

### Useful MCP Servers

**Puppeteer MCP** (`@modelcontextprotocol/server-puppeteer`):
- Allows Claude Code to navigate a site, take screenshots, inspect the DOM
- Configuration in `.claude/settings.json`:

```

json
{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}


```

**Playwright MCP** (community `playwright-mcp`):
- Same principle, multi-browser
- Useful for testing rendering across different engines (Chromium, Firefox, WebKit/Safari)

### Lighthouse via CLI

```

bash
# Installation
npm install -g lighthouse

# Mobile audit
lighthouse http://localhost:8000 --preset=perf --form-factor=mobile --output=html --output-path=./lighthouse-mobile.html

# Mobile audit in JSON (parseable)
lighthouse http://localhost:8000 --form-factor=mobile --output=json --output-path=./lighthouse-mobile.json


```

Claude Code can read the HTML report to identify issues.

### Debug with Chrome DevTools Protocol

Playwright and Puppeteer expose CDP (Chrome DevTools Protocol), providing programmatic access to:
- **Network throttling** — simulate Slow 3G/4G to detect loading bottlenecks
- **CSS coverage** — identify CSS rules never applied (dead code)
- **Performance traces** — capture a full trace to analyze rendering frame by frame

---

## Section 3: Mobile CSS Rules — complete reference

### Viewport meta tag

```

html
<!-- ✅ Correct -->
<meta name="viewport" content="width=device-width, initial-scale=1">

<!-- If using safe-area-inset -->
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">

<!-- ❌ Never do this: prevents zoom for visually impaired users -->
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no, maximum-scale=1">


```

### Base reset

```

css
*,
*::before,
*::after {
    box-sizing: border-box;
}

html {
    -webkit-text-size-adjust: 100%;
    text-size-adjust: 100%;
}

html, body {
    overflow-x: hidden;
    max-width: 100%;
}

img, video, svg {
    max-width: 100%;
    height: auto;
    display: block;
}


```

### Text alignment

Simple rule: **left by default, centered only for CTAs, never justify on mobile**.

```

css
/* Mobile base */
h1, h2, h3, h4 {
    text-align: left;
}

p, li {
    text-align: left;
}

/* CTA: centered */
.cta-wrapper {
    text-align: center;
}

/* Justify only on desktop with hyphenation */
@media (min-width: 768px) {
    .prose p {
        text-align: justify;
        hyphens: auto;
        -webkit-hyphens: auto;
    }
}


```

### Touch targets — 44×44px minimum

```

css
/* Buttons */
.btn {
    min-height: 44px;
    min-width: 44px;
    padding: 12px 20px;
    display: inline-flex;
    align-items: center;
    justify-content: center;
}

/* Navigation links */
nav a {
    display: block;
    min-height: 44px;
    padding: 12px 16px;
    line-height: 20px;
}

/* Clickable icons */
.icon-btn {
    width: 44px;
    height: 44px;
    display: flex;
    align-items: center;
    justify-content: center;
    cursor: pointer;
}

/* Enlarged tap zone without changing appearance */
.small-icon {
    position: relative;
    width: 20px;
    height: 20px;
}

.small-icon::after {
    content: '';
    position: absolute;
    inset: -12px;
}


```

### Font-size — iOS zoom prevention and readability

```

css
/* ❌ Less than 16px on inputs = automatic iOS zoom */

/* ✅ Absolute minimum on inputs */
input,
textarea,
select {
    font-size: 16px;
}

/* If different size desired on desktop */
@media (min-width: 768px) {
    input,
    textarea,
    select {
        font-size: 14px;
    }
}

/* Body text */
body {
    font-size: 16px;
    line-height: 1.6;
}

/* Fluid headings with clamp() */
h1 { font-size: clamp(1.5rem, 5vw, 2.5rem); }
h2 { font-size: clamp(1.25rem, 4vw, 2rem); }
h3 { font-size: clamp(1.1rem, 3vw, 1.5rem); }


```

### Media queries — mobile-first only

```

css
/* ✅ Mobile-first: base = mobile, add for larger screens */
.card {
    display: block;
    padding: 16px;
}

@media (min-width: 768px) {
    .card {
        display: flex;
        padding: 24px;
    }
}

@media (min-width: 1024px) {
    .card {
        padding: 32px;
    }
}

/* ❌ Desktop-first: avoid */
.card {
    display: flex;
    padding: 32px;
}

@media (max-width: 767px) {
    .card {
        display: block;
        padding: 16px;
    }
}


```

Standard breakpoints: `480px`, `768px`, `1024px`, `1280px`.

### overflow-x prevention

```

css
html, body {
    overflow-x: hidden;
    max-width: 100%;
}

/* Tables: scroll rather than breaking the layout */
.table-wrapper {
    overflow-x: auto;
}

table {
    min-width: 600px;
    width: 100%;
}

/* Debug: identify the overflowing element */
* { outline: 1px solid red; }


```

Warning: `overflow-x: hidden` on `body` can break `position: sticky`. If a sticky stops working, isolate `overflow-x: hidden` on a dedicated wrapper.

### Images and aspect-ratio

```

css
img {
    max-width: 100%;
    height: auto;
    display: block;
}

/* Fixed ratio to avoid CLS (Cumulative Layout Shift) */
.card-image {
    aspect-ratio: 4 / 3;
    width: 100%;
    object-fit: cover;
}

.hero-image {
    aspect-ratio: 16 / 9;
    width: 100%;
    object-fit: cover;
}

/* Different ratio on mobile */
@media (max-width: 767px) {
    .hero-image {
        aspect-ratio: 4 / 3;
    }
}


```

### Flex and Grid — common pitfalls

```

css
/* Flex: min-width: 0 required to prevent text overflows */
.flex-item {
    min-width: 0;
}

/* Automatic flex wrap */
.card-grid {
    display: flex;
    flex-wrap: wrap;
    gap: 16px;
}

.card-grid .card {
    flex: 1 1 280px;
    min-width: 0;
}

/* Responsive grid without media query */
.auto-grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
    gap: 16px;
}

/* Grid: single column on mobile, two columns on desktop */
.two-col {
    display: grid;
    grid-template-columns: 1fr;
    gap: 24px;
}

@media (min-width: 768px) {
    .two-col {
        grid-template-columns: 1fr 1fr;
    }
}


```

### Safe area insets (notch, navigation bar)

```

css
/* Requires viewport-fit=cover in meta tag */

.bottom-nav {
    position: fixed;
    bottom: 0;
    left: 0;
    right: 0;
    height: 56px;
    padding-bottom: env(safe-area-inset-bottom);
    background: var(--color-bg);
}

.top-header {
    position: fixed;
    top: 0;
    left: 0;
    right: 0;
    padding-top: env(safe-area-inset-top);
}

.main-content {
    padding-bottom: calc(56px + env(safe-area-inset-bottom));
    padding-left: env(safe-area-inset-left);
    padding-right: env(safe-area-inset-right);
}


```

If `viewport-fit=cover` is not defined, values equal 0 — these rules have no negative effect.

### prefers-reduced-motion

```

css
/* Animations defined normally */
.fade-in {
    animation: fadeIn 0.4s ease;
}

/* Global removal if user requests it */
@media (prefers-reduced-motion: reduce) {
    *,
    *::before,
    *::after {
        animation-duration: 0.01ms !important;
        animation-iteration-count: 1 !important;
        transition-duration: 0.01ms !important;
        scroll-behavior: auto !important;
    }
}

/* More granular approach */
@media (prefers-reduced-motion: reduce) {
    .fade-in {
        opacity: 1;
        animation: none;
    }
}


```

### prefers-color-scheme — dark mode

```

css
:root {
    --color-bg: #ffffff;
    --color-text: #1a1a1a;
    --color-text-muted: #6b7280;
    --color-border: #e5e7eb;
    --color-surface: #f9fafb;
    --color-primary: #2563eb;
    --color-primary-text: #ffffff;
    --shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}

@media (prefers-color-scheme: dark) {
    :root {
        --color-bg: #0f172a;
        --color-text: #e2e8f0;
        --color-text-muted: #94a3b8;
        --color-border: #1e293b;
        --color-surface: #1e293b;
        --color-primary: #3b82f6;
        --color-primary-text: #ffffff;
        --shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
    }

    img:not([src*=".svg"]) {
        filter: brightness(0.9);
    }
}

/* Manual toggle coexisting with system preference */
@media (prefers-color-scheme: dark) {
    :root:not([data-theme="light"]) {
        --color-bg: #0f172a;
        /* ... */
    }
}

[data-theme="dark"] {
    --color-bg: #0f172a;
    /* ... */
}

[data-theme="light"] {
    --color-bg: #ffffff;
    /* ... */
}


```

### Forms

```

css
input[type="text"],
input[type="email"],
input[type="password"],
input[type="tel"],
input[type="number"],
textarea,
select {
    width: 100%;
    font-size: 16px; /* required — prevents iOS zoom */
    padding: 12px 16px;
    min-height: 44px;
    border-radius: 8px;
    border: 1px solid var(--color-border);
    -webkit-appearance: none;
    appearance: none;
    background: var(--color-bg);
    color: var(--color-text);
}

label {
    display: block;
    font-size: 16px;
    margin-bottom: 6px;
    font-weight: 500;
}

.form-group {
    margin-bottom: 20px;
}


```

HTML attributes not to forget (CSS can't replace them):

```

html
<!-- Numeric keyboard -->
<input type="text" inputmode="numeric">

<!-- Decimal keyboard -->
<input type="text" inputmode="decimal">

<!-- Email keyboard with direct @ -->
<input type="email" inputmode="email">

<!-- URL keyboard -->
<input type="url" inputmode="url">


```

### Minimum lateral spacing

```

css
.container {
    padding-left: 16px;  /* absolute minimum on mobile */
    padding-right: 16px;
    max-width: 1200px;
    margin: 0 auto;
}

@media (min-width: 768px) {
    .container {
        padding-left: 24px;
        padding-right: 24px;
    }
}

@media (min-width: 1024px) {
    .container {
        padding-left: 32px;
        padding-right: 32px;
    }
}


```

---

## Section 4: CSS Conventions — generic rules

### CSS custom properties for theming

Always define repeated values as custom properties. Never hard-code colors or spacing values scattered throughout CSS.

```

css
:root {
    /* Colors */
    --color-primary: #2563eb;
    --color-primary-hover: #1d4ed8;
    --color-bg: #ffffff;
    --color-text: #1a1a1a;
    --color-text-muted: #6b7280;
    --color-border: #e5e7eb;
    --color-surface: #f9fafb;
    --color-danger: #dc2626;
    --color-success: #16a34a;

    /* Spacing */
    --space-xs: 4px;
    --space-sm: 8px;
    --space-md: 16px;
    --space-lg: 24px;
    --space-xl: 32px;
    --space-2xl: 48px;

    /* Typography */
    --font-size-sm: 0.875rem;
    --font-size-base: 1rem;
    --font-size-lg: 1.125rem;
    --font-size-xl: 1.25rem;
    --line-height-base: 1.6;
    --line-height-tight: 1.3;

    /* Radii */
    --radius-sm: 4px;
    --radius-md: 8px;
    --radius-lg: 12px;
    --radius-full: 9999px;

    /* Shadows */
    --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
    --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.07);
    --shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);

    /* Transitions */
    --transition-fast: 0.15s ease;
    --transition-base: 0.25s ease;
}


```

### Naming conventions

Be consistent. BEM or utility-first, not both mixed in the same project.

**BEM** (recommended for isolated components):

```

css
/* Block */
.card {}

/* Element */
.card__title {}
.card__body {}
.card__footer {}

/* Modifier */
.card--featured {}
.card--compact {}
.card__title--large {}


```

### Accessibility

**focus-visible** — never remove the outline without replacing it:

```

css
/* ❌ Never do this */
* { outline: none; }
:focus { outline: none; }

/* ✅ Replace the native outline with a custom style */
:focus-visible {
    outline: 2px solid var(--color-primary);
    outline-offset: 2px;
    border-radius: 2px;
}

/* Remove outline only for mouse clicks (not keyboard) */
:focus:not(:focus-visible) {
    outline: none;
}


```

**WCAG AA contrasts**:

| Context | Minimum ratio |
|---------|--------------|
| Normal text (< 18px) | 4.5:1 |
| Large text (≥ 18px or ≥ 14px bold) | 3:1 |
| UI components, icons | 3:1 |

### CSS performance

```

css
/* ❌ Triggers repaint on every animation frame */
.card:hover {
    box-shadow: 0 8px 30px rgba(0,0,0,0.2);
}

/* ✅ Better: prepare the shadow on load, change opacity */
.card {
    box-shadow: 0 8px 30px rgba(0,0,0,0);
    transition: box-shadow var(--transition-base);
}
.card:hover {
    box-shadow: 0 8px 30px rgba(0,0,0,0.2);
}

/* ✅ Use opacity or transform — composited on GPU */
.element {
    transform: translateY(0);
    opacity: 1;
    transition: transform var(--transition-base), opacity var(--transition-base);
}

.element.hidden {
    transform: translateY(8px);
    opacity: 0;
}


```

### Modern CSS to prefer

```

css
/* clamp() — fluid sizes without media queries */
h1 { font-size: clamp(1.5rem, 5vw, 2.5rem); }
.container { padding: clamp(16px, 4vw, 48px); }

/* gap — more readable than margin on children */
.grid {
    display: flex;
    gap: 24px;
}

/* aspect-ratio — more reliable than the padding-top hack */
.video-wrapper {
    aspect-ratio: 16 / 9;
    width: 100%;
}

/* Logical properties — for multilingual support (RTL/LTR) */
.card {
    margin-inline: auto;
    padding-block: 24px;
    border-inline-start: 3px solid var(--color-primary);
}

/* inset — replaces top/right/bottom/left */
.overlay {
    position: fixed;
    inset: 0;
}


```

### Rule on !important

`!important` is accepted only in two cases:
1. Utility classes (`.sr-only`, `.hidden`, `.visually-hidden`) — by convention
2. Overriding third-party styles you don't control (plugins, libraries)

Outside these cases, a `!important` signals a specificity problem to fix at the source.

---

## Section 5: Test checklist

### Devices to test

| Device | Width | Priority |
|--------|-------|----------|
| iPhone SE (2020/2022) | 375px | High — narrowest mainstream screen |
| iPhone 14 / 15 | 390px | High — current iOS reference |
| Android mid-range (Pixel 6a, Samsung A54) | 360–412px | High |
| iPad / iPad Mini | 768px | Medium |
| Desktop laptop | 1280–1440px | Baseline |

### Modes to test

- [ ] Portrait (default)
- [ ] Landscape
- [ ] Dark mode
- [ ] Reduced motion
- [ ] Text zoom at 150%

### Lighthouse — targets

| Score | Target |
|-------|--------|
| Performance | ≥ 80 |
| Accessibility | ≥ 90 |
| Best Practices | ≥ 90 |
| SEO | ≥ 90 |

### Final checklist

- [ ] No horizontal scroll on any tested device
- [ ] All interactive elements keyboard accessible (Tab + Enter/Space)
- [ ] focus-visible visible and distinctive
- [ ] All inputs with font-size ≥ 16px
- [ ] Text with contrast ≥ 4.5:1 (normal) or 3:1 (large)
- [ ] Images with descriptive `alt` or `alt=""` if decorative
- [ ] Forms with `<label>` associated to each input
- [ ] Dark mode: readable text, no blinding white
- [ ] Reduced motion: no animation still playing
- [ ] Lighthouse Accessibility ≥ 90
- [ ] No automatic iOS zoom on inputs
- [ ] Touch targets ≥ 44×44px
```

`

## Download the file

The file is available directly: [Download the CLAUDE.md](https://www.web-developpeur.com/blog/claude-md/contexts/mobile-css-redesign.md). Drop it at the project root or in `.claude/`.

## What's next

The idea behind this file is to build a collection of specialized CLAUDE.md files by task type. Not a generic CLAUDE.md that tries to cover everything and becomes unreadable, but targeted files you activate based on the current work. Mobile CSS, Go unit tests, PostgreSQL migrations, security audit — each with its precise context, targets, and pitfalls.

This one is the first in the series. If you have specialized contexts you already use, or tasks for which you'd like a file of the same kind, the comments are open.

**📄 Associated CLAUDE.md**

[View](https://www.web-developpeur.com/blog/claude-md/view.php?ctx=mobile-css-redesign) • [Download](https://www.web-developpeur.com/blog/claude-md/contexts/mobile-css-redesign.md) • [Catalogue](https://www.web-developpeur.com/blog/claude-md/)

Mobile CSS consistency: all best practices in 2026

Odilon HUGONNOT — Fri, 15 May 2026 09:00:02 +0000

We've all done it: build the interface on a 1440px screen, drag the window to shrink it, decide it "looks fine", and ship to production. Two days later, a user reports that the submit button is too small to tap, that justified text looks like swiss cheese on their iPhone SE, and that the login form triggers automatic Safari zoom. All of it avoidable. In 2026, mobile accounts for over 60% of global web traffic. It's no longer an edge case — it's the primary case.

Here are the concrete CSS rules, organized by theme. No theory: code that works and explanations for why the alternative fails.

Viewport and document base

Before any CSS, the meta viewport tag in the <head>. Without it, mobile browsers simulate a desktop screen and reduce zoom — all responsive CSS becomes useless.

<meta name="viewport" content="width=device-width, initial-scale=1">

Do not add user-scalable=no or maximum-scale=1. This is a disastrous accessibility practice: it prevents visually impaired users from zooming. Apple actually removed the effect of user-scalable=no in iOS 10 for this reason. Useless and harmful.

Then, the basic reset that avoids surprises:

*,
*::before,
*::after {
    box-sizing: border-box;
}

html {
    /* Prevents automatic text enlargement on rotation */
    -webkit-text-size-adjust: 100%;
    text-size-adjust: 100%;
}

Text alignment: the simple rule

Justified text (text-align: justify) looks clean on desktop with a 700px column. On mobile with a 320px column, the hyphenation algorithm creates irregular inter-word spacing, sometimes grotesque. Some mobile browsers don't handle automatic hyphenation (hyphens: auto) correctly. Result: holes in the text, degraded readability.

The rule to follow:

Headings h1–h4: left-aligned. Easier to scan, the eye always knows where to resume.
Body text / paragraphs: left-aligned. Justified on mobile is a bad idea in almost all cases.
CTA buttons: centered. Catches the eye and is easier to tap with the thumb.
Lists: left-aligned. The bullet/number already does the visual work.

/* Base rule — applies from mobile up */
h1, h2, h3, h4 {
    text-align: left;
}

p, li {
    text-align: left;
    /* No justify on mobile */
}

/* If you want justify on desktop only */
@media (min-width: 768px) {
    .prose p {
        text-align: justify;
        hyphens: auto;
        -webkit-hyphens: auto;
    }
}

/* CTA buttons: centered */
.cta-wrapper {
    text-align: center;
}

.btn-cta {
    display: inline-block;
}

Touch targets: 44×44px minimum

Apple recommends 44×44pt, Google Material Design recommends 48×48dp. The basic rule: every interactive element (button, nav link, checkbox, clickable icon) must have a tap zone of at least 44×44px. A 12px-tall link is unusable with a thumb without a magnifier.

/* Buttons: guaranteed minimum size */
.btn {
    min-height: 44px;
    min-width: 44px;
    padding: 12px 20px;
    display: inline-flex;
    align-items: center;
    justify-content: center;
}

/* Navigation links */
nav a {
    display: block;
    min-height: 44px;
    padding: 12px 16px;
    line-height: 20px;
}

/* Inline links in text: enlarged tap zone without touching the layout */
.text-link {
    padding: 4px 0;
    /* The tap zone will be taller than the text */
}

/* Clickable icons (burger menu, close, etc.) */
.icon-btn {
    width: 44px;
    height: 44px;
    display: flex;
    align-items: center;
    justify-content: center;
    cursor: pointer;
}

If an element is visually small (20×20px icon) but needs to be tappable, you can enlarge the click zone without changing the appearance using ::after:

.small-icon {
    position: relative;
    width: 20px;
    height: 20px;
}

.small-icon::after {
    content: '';
    position: absolute;
    inset: -12px; /* enlarges the tap zone by 12px in each direction */
}

Font sizes: the iOS zoom pitfall

Safari on iOS automatically zooms into a form field when the font size is below 16px. It's "helpful" but it breaks the entire page layout. The fix is simple: never go below 16px on inputs.

/* Prevents automatic iOS zoom on inputs */
input,
textarea,
select {
    font-size: 16px; /* Absolute minimum on mobile */
}

/* If you want a different size on desktop */
@media (min-width: 768px) {
    input,
    textarea,
    select {
        font-size: 14px; /* OK on desktop */
    }
}

/* Body text: 16px minimum on mobile */
body {
    font-size: 16px;
    line-height: 1.6;
}

/* Headings: adapt without going too small */
h1 { font-size: clamp(1.5rem, 5vw, 2.5rem); }
h2 { font-size: clamp(1.25rem, 4vw, 2rem); }
h3 { font-size: clamp(1.1rem, 3vw, 1.5rem); }

clamp() is well supported (Chrome 79+, Firefox 75+, Safari 13.1+) and avoids writing media queries for every heading. The syntax: clamp(min, preferred, max). The "preferred" value in vw allows a smooth progression between breakpoints.

Media queries: mobile-first or desktop-first?

This debate has a clear answer. Mobile-first wins, for concrete reasons:

Base CSS applies to mobile devices without overriding media queries
You don't override mobile styles with desktop — you build on them
Slightly better performance: mobile browsers parse fewer conditional rules

/* ✅ Mobile-first: start from mobile, add for larger screens */
.card {
    display: block;
    padding: 16px;
}

@media (min-width: 768px) {
    .card {
        display: flex;
        padding: 24px;
    }
}

@media (min-width: 1024px) {
    .card {
        padding: 32px;
    }
}

/* ❌ Desktop-first: start from desktop, override for mobile */
.card {
    display: flex;
    padding: 32px;
}

@media (max-width: 1023px) {
    .card {
        padding: 24px;
    }
}

@media (max-width: 767px) {
    .card {
        display: block;
        padding: 16px;
    }
}

In practice, both approaches often coexist in a legacy codebase. What matters: be consistent within a given component, don't mix both approaches in the same rules.

Horizontal scroll: the overflow-x trap

Unintentional horizontal scroll on mobile is one of the most common and most painful bugs to debug. Typical causes: an element with a fixed width larger than 100vw, a forgotten white-space: nowrap, a translate going off-screen, an image with no width constraint.

/* Global prevention */
html, body {
    overflow-x: hidden;
    max-width: 100%;
}

/* Responsive images — basic rule */
img, video, svg {
    max-width: 100%;
    height: auto;
}

/* Tables: allow horizontal scroll rather than breaking the layout */
.table-wrapper {
    overflow-x: auto;
    -webkit-overflow-scrolling: touch;
}

table {
    min-width: 600px; /* or whatever width is needed */
    width: 100%;
}

Warning: overflow-x: hidden on body can interfere with position: sticky elements. If a sticky stops working, it's usually an ancestor with overflow that's blocking it. In that case, isolate overflow-x: hidden on a specific wrapper rather than on body.

To debug a mysterious horizontal scroll:

/* Temporary debug: identify which element is overflowing */
* {
    outline: 1px solid red;
}

Spacing and mobile-friendly padding

On mobile, space is precious but thumbs need room. The minimum lateral padding to avoid content flush against the edge: 16px. 20px is more comfortable.

.container {
    padding-left: 16px;
    padding-right: 16px;
    max-width: 1200px;
    margin: 0 auto;
}

@media (min-width: 768px) {
    .container {
        padding-left: 24px;
        padding-right: 24px;
    }
}

@media (min-width: 1024px) {
    .container {
        padding-left: 32px;
        padding-right: 32px;
    }
}

/* Vertical spacing between sections */
.section {
    padding-top: 40px;
    padding-bottom: 40px;
}

@media (min-width: 768px) {
    .section {
        padding-top: 64px;
        padding-bottom: 64px;
    }
}

Mobile forms

Beyond the font-size: 16px already mentioned, forms on mobile have other particularities.

/* Full-width inputs on mobile */
input[type="text"],
input[type="email"],
input[type="password"],
input[type="tel"],
textarea,
select {
    width: 100%;
    font-size: 16px; /* Prevents iOS zoom */
    padding: 12px 16px;
    min-height: 44px;
    border-radius: 8px;
    border: 1px solid #ccc;
    /* Removes native iOS styling for more control */
    -webkit-appearance: none;
    appearance: none;
}

/* Numeric keyboard on mobile for appropriate fields */
/* (HTML, not CSS, but often forgotten) */
/* <input type="tel" inputmode="numeric"> */
/* <input type="text" inputmode="decimal"> */

/* Labels: readable size, sufficient spacing */
label {
    display: block;
    font-size: 16px;
    margin-bottom: 6px;
    font-weight: 500;
}

/* Spacing between fields */
.form-group {
    margin-bottom: 20px;
}

The inputmode attribute (HTML, not CSS) is crucial for displaying the right virtual keyboard: numeric for codes, decimal for amounts, email for emails (shows the @ directly), url for URLs. It costs nothing and significantly improves UX.

Flexbox and Grid: mobile pitfalls

Flexbox and Grid work well on mobile, but a few behaviors can surprise you.

/* Flex: avoid unintentional shrinking */
.flex-item {
    flex-shrink: 0; /* If the element shouldn't shrink */
    min-width: 0;   /* Classic fix: flex items have min-width: auto by default,
                       which prevents text from wrapping */
}

/* Flex wrap to switch to column on mobile */
.card-grid {
    display: flex;
    flex-wrap: wrap;
    gap: 16px;
}

.card-grid .card {
    flex: 1 1 280px; /* Grows, shrinks, base 280px → automatic wrap on mobile */
    min-width: 0;
}

/* Responsive grid without media queries */
.auto-grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
    gap: 16px;
}

/* Grid: single column on mobile */
.two-col {
    display: grid;
    grid-template-columns: 1fr;
    gap: 24px;
}

@media (min-width: 768px) {
    .two-col {
        grid-template-columns: 1fr 1fr;
    }
}

The min-width: 0 on flex items is a fix to know by heart. Without it, a long word or a URL inside a flex item can overflow its container even with overflow: hidden or word-break: break-all.

Safe area insets for notched phones

Since the iPhone X and its Android competitors, phones have notches, dynamic islands, and rounded navigation bars that can overlap content. The env(safe-area-inset-*) values let you account for them.

/* Extended viewport to use the full surface */
/* In the meta viewport: viewport-fit=cover is required */
/* <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover"> */

/* Fixed bottom navigation (common pattern on mobile) */
.bottom-nav {
    position: fixed;
    bottom: 0;
    left: 0;
    right: 0;
    height: 56px;
    padding-bottom: env(safe-area-inset-bottom);
    background: #fff;
    border-top: 1px solid #e0e0e0;
}

/* Fixed top header */
.top-header {
    position: fixed;
    top: 0;
    left: 0;
    right: 0;
    padding-top: env(safe-area-inset-top);
}

/* Main content: margin to avoid overlap */
.main-content {
    padding-bottom: calc(56px + env(safe-area-inset-bottom));
    padding-left: env(safe-area-inset-left);
    padding-right: env(safe-area-inset-right);
}

If the site doesn't use viewport-fit=cover, safe area insets equal 0 and these rules have no effect — no risk of breaking anything by adding them.

Mobile navigation: hamburger and patterns

No magic CSS here, but a few rules that avoid classic mistakes:

/* Hamburger menu: hidden on desktop, visible on mobile */
.nav-toggle {
    display: flex;
    align-items: center;
    justify-content: center;
    width: 44px;
    height: 44px;
    background: none;
    border: none;
    cursor: pointer;
    padding: 0;
}

@media (min-width: 768px) {
    .nav-toggle {
        display: none;
    }
}

/* Mobile nav: clean transition */
.nav-menu {
    display: none;
    flex-direction: column;
    position: fixed;
    inset: 0;
    background: #fff;
    z-index: 1000;
    padding: 60px 24px 24px;
    overflow-y: auto;
}

.nav-menu.is-open {
    display: flex;
}

/* Or version with transition */
.nav-menu {
    position: fixed;
    inset: 0;
    background: #fff;
    z-index: 1000;
    padding: 60px 24px 24px;
    overflow-y: auto;
    transform: translateX(-100%);
    transition: transform 0.25s ease;
}

.nav-menu.is-open {
    transform: translateX(0);
}

/* Menu links: large enough to tap */
.nav-menu a {
    display: block;
    padding: 16px 0;
    font-size: 18px;
    border-bottom: 1px solid #f0f0f0;
    text-decoration: none;
    color: inherit;
}

@media (min-width: 768px) {
    .nav-menu {
        position: static;
        transform: none;
        display: flex;
        flex-direction: row;
        padding: 0;
        gap: 24px;
    }

    .nav-menu a {
        padding: 8px 0;
        font-size: 16px;
        border-bottom: none;
    }
}

Performance: prefers-reduced-motion

Some users have configured their system to reduce animations (epilepsy, vestibular disorders, personal preference). The prefers-reduced-motion media query lets you respect their choice.

/* Default animations */
.fade-in {
    animation: fadeIn 0.4s ease;
}

.slide-up {
    animation: slideUp 0.3s ease;
}

/* Remove animations if the user requests it */
@media (prefers-reduced-motion: reduce) {
    *,
    *::before,
    *::after {
        animation-duration: 0.01ms !important;
        animation-iteration-count: 1 !important;
        transition-duration: 0.01ms !important;
        scroll-behavior: auto !important;
    }
}

/* More granular approach: remove only decorative animations */
@media (prefers-reduced-motion: reduce) {
    .decorative-animation {
        animation: none;
    }

    .fade-in {
        opacity: 1; /* Show directly without fade */
    }
}

On mobile, this has an additional impact: animations drain battery. Respecting prefers-reduced-motion also means being more resource-efficient.

Dark mode with prefers-color-scheme

Dark mode has been OS-managed since iOS 13 and Android 10. Users expect web applications to respect their system preference.

/* CSS variables: clean approach for dark mode */
:root {
    --color-bg: #ffffff;
    --color-text: #1a1a1a;
    --color-text-muted: #6b7280;
    --color-border: #e5e7eb;
    --color-surface: #f9fafb;
    --color-primary: #2563eb;
    --color-primary-text: #ffffff;
    --shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}

@media (prefers-color-scheme: dark) {
    :root {
        --color-bg: #0f172a;
        --color-text: #e2e8f0;
        --color-text-muted: #94a3b8;
        --color-border: #1e293b;
        --color-surface: #1e293b;
        --color-primary: #3b82f6;
        --color-primary-text: #ffffff;
        --shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
    }
}

/* Usage */
body {
    background-color: var(--color-bg);
    color: var(--color-text);
}

.card {
    background: var(--color-surface);
    border: 1px solid var(--color-border);
    box-shadow: var(--shadow);
}

/* Images: slightly dim in dark mode to reduce glare */
@media (prefers-color-scheme: dark) {
    img:not([src*=".svg"]) {
        filter: brightness(0.9);
    }
}

If the site also implements a manual toggle (light/dark button), you need to manage coexistence with the system preference. The classic approach: add a data-theme="dark" class on <html> when the user toggles manually, and scope the variables accordingly.

/* System preference */
@media (prefers-color-scheme: dark) {
    :root:not([data-theme="light"]) {
        --color-bg: #0f172a;
        /* ... */
    }
}

/* Manual override: dark */
[data-theme="dark"] {
    --color-bg: #0f172a;
    /* ... */
}

/* Manual override: light (takes priority over system dark preference) */
[data-theme="light"] {
    --color-bg: #ffffff;
    /* ... */
}

Scroll behavior and -webkit-overflow-scrolling

iOS native scroll has a momentum (inertia) effect that is sometimes missing in custom scrollable areas. Historically, -webkit-overflow-scrolling: touch was added to enable it. It's now the default behavior since iOS 13. The property is deprecated but harmless if it lingers in legacy code.

/* Smooth scroll for anchor links */
html {
    scroll-behavior: smooth;
}

/* Respect prefers-reduced-motion */
@media (prefers-reduced-motion: reduce) {
    html {
        scroll-behavior: auto;
    }
}

/* Custom scrollable area with scroll snap */
.carousel {
    display: flex;
    overflow-x: auto;
    scroll-snap-type: x mandatory;
    gap: 16px;
    padding: 16px;
    /* Hide scrollbar on desktop, keep the scroll */
    scrollbar-width: none; /* Firefox */
    -ms-overflow-style: none; /* IE/Edge */
}

.carousel::-webkit-scrollbar {
    display: none; /* Chrome/Safari */
}

.carousel-item {
    scroll-snap-align: start;
    flex-shrink: 0;
    width: 280px;
}

Images: max-width and aspect-ratio

/* Responsive base */
img {
    max-width: 100%;
    height: auto;
    display: block;
}

/* Avoid layout shift (CLS) with aspect-ratio */
.product-image {
    aspect-ratio: 4 / 3;
    width: 100%;
    object-fit: cover;
    border-radius: 8px;
}

/* Full-width hero image */
.hero-image {
    aspect-ratio: 16 / 9;
    width: 100%;
    object-fit: cover;
}

/* On mobile, squarer ratio */
@media (max-width: 767px) {
    .hero-image {
        aspect-ratio: 4 / 3;
    }
}

/* Images with loading background */
.lazy-image {
    background-color: #f0f0f0;
    aspect-ratio: 16 / 9;
    width: 100%;
}

aspect-ratio is well supported (Chrome 88+, Firefox 89+, Safari 15+) and advantageously replaces the old padding-top hack technique for maintaining the ratio of an image before it loads.

Summary: rules to apply by default

Viewport: width=device-width, initial-scale=1 without user-scalable=no
Box-sizing: border-box on everything
Text-size-adjust: 100% to prevent automatic enlargement
Alignment: headings and body left-aligned, CTA buttons centered, no justify on mobile
Touch targets: 44×44px minimum for everything clickable
Input font-size: 16px minimum, otherwise automatic iOS zoom
Body text: 16px minimum, line-height 1.5–1.6
Media queries: mobile-first (min-width)
Overflow-x: hidden on html/body, tables in a scrollable wrapper
Images: max-width: 100%, aspect-ratio to avoid CLS
Forms: width: 100% on inputs, appropriate inputmode in HTML
Flex items: min-width: 0 to avoid overflows
Safe areas: env(safe-area-inset-*) for fixed elements with viewport-fit=cover
prefers-reduced-motion: remove or attenuate animations
prefers-color-scheme: CSS variables for dark mode
Scroll snap: for native horizontal carousels

None of these rules are revolutionary. What is, is applying them systematically from the start of the project rather than fixing them one by one after user reports.

Docker + Symfony + WSL2: the 3 first-day problems

Odilon HUGONNOT — Thu, 14 May 2026 09:00:02 +0000

New Symfony 7 project. Target stack: PostgreSQL 16, Redis 7, Apache (not Nginx — personal preference, more on that later). Dev environment: WSL2 on Windows. In theory, Docker + WSL2 has been smooth for a few versions now.

In practice, there are 3 problems that show up systematically on day one, that aren't documented together anywhere, and that waste an hour every time. Here's how to avoid them.

The final stack

The complete docker-compose.yml:

services:
  app:
    build: .
    ports:
      - "8080:80"
    volumes:
      - .:/var/www/html
    depends_on:
      - db
      - redis
    environment:
      DATABASE_URL: "postgresql://app:password@db:5432/touspourris"

  db:
    image: postgres:16-alpine
    ports:
      - "5433:5432"   # 5433 on host, not 5432
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: password
      POSTGRES_DB: touspourris
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  postgres_data:

The detail that matters: the 5433:5432 port mapping for PostgreSQL. This is the heart of the first problem.

Problem 1 — The PostgreSQL port conflict

If you have PostgreSQL installed locally on WSL2 — which is common on a dev machine — it's already listening on port 5432. docker compose up starts the PostgreSQL container and tries to bind 5432:5432: immediate conflict.

Error response from daemon: driver failed programming external connectivity on endpoint db:
Bind for 0.0.0.0:5432 failed: port is already allocated

Fix: map to 5433 on the host side (5433:5432 in docker-compose.yml). The container keeps listening on 5432 internally — other Docker services reach it without changing their config. The DATABASE_URL variable points to db:5432, not to the host. Only the port exposed to the host changes.

To connect from the host (DBeaver, psql): localhost:5433. That's all.

Problem 2 — Docker group permissions under WSL2

After installing Docker Engine (not Docker Desktop):

sudo apt install docker.io
sudo usermod -aG docker $USER

Instinct: run docker ps. Result:

permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

The reason: usermod -aG docker $USER modifies the group for new sessions, not the current one. Two solutions:

# Option 1: activate the group in the current session (temporary)
newgrp docker

# Option 2: fully restart WSL2 (permanent)
# In Windows PowerShell:
wsl --shutdown
# Then relaunch WSL2

newgrp docker opens a subshell with the new group. It works, but only for the current terminal. wsl --shutdown is the permanent fix — WSL2 restarts with groups correctly applied.

Problem 3 — Docker daemon not started when WSL2 launches

WSL2 doesn't start systemd by default (depending on the distro). The Docker daemon doesn't run automatically at startup. First Docker command of the morning:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

Two solutions:

# Option 1: start manually each time
sudo service docker start

# Option 2: enable systemd in WSL2 (Ubuntu 22.04+)
# In /etc/wsl.conf:
[boot]
systemd=true

With systemd=true, Docker starts automatically as a system service. This is the clean solution if your distro supports it. After modifying /etc/wsl.conf, run wsl --shutdown from PowerShell for the change to take effect.

Apache vs Nginx in Docker

Deliberate choice of Apache over Nginx for the app container. Main reason: familiarity with Apache config for Symfony (standard .htaccess, mod_rewrite enabled). Nginx is often recommended for prod performance, but in dev the difference is zero and the extra configuration cost isn't justified.

The Dockerfile for Symfony + Apache:

FROM php:8.3-apache

RUN apt-get update && apt-get install -y \
    git zip unzip libpq-dev \
    && docker-php-ext-install pdo pdo_pgsql \
    && a2enmod rewrite

COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

WORKDIR /var/www/html
COPY . .

RUN composer install --no-dev --optimize-autoloader

RUN chown -R www-data:www-data var/

The pdo_pgsql extension is essential — without it, Doctrine throws an exception on the first call. a2enmod rewrite enables the Apache module so that Symfony's router works. The final chown prevents permission errors on the cache and logs.

The Makefile as a single interface

With Docker, commands get long. A Makefile at the root fixes that:

up:
    docker compose up -d

down:
    docker compose down

shell:
    docker compose exec app bash

console:
    docker compose exec app php bin/console $(cmd)

migrate:
    docker compose exec app php bin/console doctrine:migrations:migrate --no-interaction

Usage: make up, make shell, make console cmd="cache:clear". Everyone on the project uses the same commands without knowing the exact Docker syntax. And new team members have a documented entry point without having to read the entire docker-compose.yml.

Conclusion

The 3 problems — port conflict, group permissions, daemon startup — are independent but all show up on day one. None of them are documented together in official Docker guides for WSL2. By solving them cleanly once (5433 for PG, wsl --shutdown, systemd=true), the setup becomes stable and reproducible.

The rest — Symfony, PostgreSQL, Redis — works just like any standard Docker stack. The problem wasn't Docker, it was the WSL2 environment underneath.

📄 Associated CLAUDE.md

View • Download • Catalogue

PHP async: event loop, Fibers and the limits of single-threading

Odilon HUGONNOT — Wed, 13 May 2026 09:00:01 +0000

A colleague asks: "Can PHP do what Node.js does — jump between tasks on a single thread?" Short answer: yes. Long answer: it's more subtle than that, and the distinction between concurrency and parallelism changes everything.

PHP has a reputation for being sequential and blocking. That's true in the classic Apache + PHP-FPM model. But it's far from inevitable — understanding why it blocks is the first step toward knowing when and how to stop letting it.

The blocking model of PHP-FPM

In PHP-FPM, each HTTP request is handled by an isolated worker. That worker is single-threaded: operations execute one after another, in order. Nothing can happen concurrently within the same process.

Concretely, if your handler makes three HTTP calls to external APIs, they chain sequentially:

t=0ms   → call API users    (200ms waiting on network)
t=200ms → call API orders   (200ms waiting on network)
t=400ms → call API products (200ms waiting on network)
t=600ms → response sent back to client

600 ms. For 580 of those 600 ms, the thread does nothing — it's waiting on network responses. The CPU is idle, but the thread is blocked on I/O. That's where async becomes interesting: that waiting time can be used to make progress on other tasks.

PHP CLI follows the same model: a single thread, sequential execution. The difference from PHP-FPM is that a script can run for a long time — which makes the event loop viable, since you have a persistent process capable of running an event loop.

The event loop: cooperative concurrency

The event loop principle is straightforward: instead of blocking the thread waiting for an I/O response, you register a callback that will be called when the response arrives, then move on to the next task. The thread never sleeps — it loops checking which events are ready to be handled.

ReactPHP is the library that implements this model in PHP. The simplest example to understand the mechanics:

$loop = React\EventLoop\Factory::create();

$loop->addTimer(1, function () { echo "Task A\n"; });
$loop->addTimer(2, function () { echo "Task B\n"; });

$loop->run();

A single thread. Both timers run in the same loop. While waiting for the first second, nothing blocks the thread — the event loop can handle other events in the meantime. This is cooperative concurrency: tasks voluntarily share the thread by yielding control when they wait.

The concrete case that justifies the investment: three HTTP calls in parallel instead of sequential. With React\Http\Browser:

$loop    = React\EventLoop\Factory::create();
$browser = new React\Http\Browser($loop);

$promises = [
    $browser->get('https://api.example.com/users'),
    $browser->get('https://api.example.com/orders'),
    $browser->get('https://api.example.com/products'),
];

React\Promise\all($promises)->then(function (array $responses) {
    foreach ($responses as $response) {
        echo $response->getBody() . "\n";
    }
});

$loop->run();

All three requests are fired simultaneously. The event loop waits for responses and processes each callback as a response arrives. Result: ~200 ms instead of 600 ms. The gain comes entirely from overlapping network wait time — no CPU parallelism, no additional threads.

PHP 8.1 Fibers: native cooperative multitasking

Fibers, introduced in PHP 8.1, are a low-level mechanism for cooperative multitasking. A Fiber can suspend its execution and hand control back to the caller, which can decide to resume the Fiber later with a value.

$fiber = new Fiber(function (): void {
    $value = Fiber::suspend('first suspension');
    echo "Resumed with: " . $value . "\n";
});

$value = $fiber->start();          // starts the Fiber, receives the suspended value
echo "Suspended with: " . $value . "\n";
$fiber->resume('hello');            // resumes the Fiber with a value

Which outputs:

Suspended with: first suspension
Resumed with: hello

A Fiber is essentially a pausable execution context. It doesn't run in parallel with the main code — it explicitly yields control via Fiber::suspend(). That's the heart of cooperative multitasking: each Fiber is responsible for knowing when to yield.

Fibers alone aren't enough to build a usable async system. You need a scheduler that manages the list of active Fibers, resumes those that can make progress, and integrates an event loop for I/O operations. That's what Amphp v3 provides. With Amp, writing async code looks like synchronous code:

use Amp\Http\Client\HttpClientBuilder;

$client = HttpClientBuilder::buildDefault();

// These three calls are launched concurrently,
// but the code reads as if it were sequential
$responses = Amp\Future\awaitAll([
    async(fn() => $client->request(new Request('https://api.example.com/users'))),
    async(fn() => $client->request(new Request('https://api.example.com/orders'))),
    async(fn() => $client->request(new Request('https://api.example.com/products'))),
]);

Readability is Amp's main argument over ReactPHP: no callback chains, no manual promise management. The scheduler handles Fiber suspension and resumption behind the scenes.

What async doesn't solve

Async only solves the problem of time wasted waiting on I/O. If the task is CPU-bound — cryptographic computation, image processing, heavy parsing — there's nothing to gain. The thread is running at 100 %, and suspending the Fiber just delays the work without letting another task execute in the meantime.

The concrete distinction: an HTTP call that takes 200 ms is 199 ms of waiting during which the CPU is free. A bcrypt hash that takes 200 ms is 200 ms of CPU at full load. The event loop helps in the first case, not the second.

The database case is more nuanced. PDO, PHP's default driver, is entirely blocking: a SQL query blocks the thread until the response. With ReactPHP or Amp, using PDO inside a Fiber cancels all the benefit — the Fiber blocks like classic synchronous code. You need native async drivers: amphp/mysql or amphp/postgres for PostgreSQL. Adoption of these drivers is still limited, which makes the Amp + PostgreSQL stack less natural than its Node.js equivalent.

Another limit not to underestimate: synchronous PHP extensions. If a third-party library internally calls a blocking network function (curl without async, some SDKs), the entire loop freezes during that call. The event loop can't do anything against blocking code it doesn't control.

True parallelism: when the event loop isn't enough

When the bottleneck is pure computation rather than I/O waiting, or when you genuinely need multiple CPU threads, PHP has other options — less elegant, but functional.

pcntl_fork — available in PHP CLI, creates a child process that inherits the parent context. Simple for parallelising independent tasks, but watch shared resource management (DB connections, files):

$pid = pcntl_fork();

if ($pid === 0) {
    // Child process
    processHeavyTask();
    exit(0);
} else {
    // Parent process continues
    doOtherWork();
    pcntl_waitpid($pid, $status); // wait for child to finish
}

ext-parallel — a PECL extension that exposes real PHP threads with controlled memory sharing. Cleaner than fork for CPU-bound tasks, but the extension isn't available on all installations and its API surface is limited (only stateless functions can be sent to a thread).

External workers — the most pragmatic solution in production: delegate heavy work to a queue (Redis, RabbitMQ, Beanstalkd) consumed by separate PHP-FPM workers. Symfony Messenger handles this cleanly. The web application stays responsive, heavy tasks execute outside the request/response cycle.

Horizontal scaling of PHP-FPM itself is also a valid answer: multiple workers handle multiple requests in parallel — not in the same thread, but in separate processes managed by the FPM pool. That's the default production model, and for most web applications, it's enough.

Conclusion

PHP can do cooperative concurrency. ReactPHP and Amp have been proving it in production for years. Fibers in PHP 8.1 finally gave a clean native primitive for building schedulers, and Amp v3 makes excellent use of them.

But the answer to "should you go async in PHP?" depends entirely on the problem. If the bottleneck is waiting on network responses in a long-running CLI script — yes, ReactPHP or Amp make sense. If it's a classic web API with a few SQL queries — PHP-FPM with multiple workers, maybe a Redis cache, solves the problem without adding the complexity of an event loop.

What's certain: the argument "PHP can't do async" is wrong. The argument "PHP with an event loop fits all Node.js use cases" is equally wrong. As usual, the nuance is in the load model, not the language.

Bilingual FR/EN blog in pure PHP: architecture without framework or database

Odilon HUGONNOT — Tue, 12 May 2026 09:00:04 +0000

This blog was built in pure PHP, no CMS, no database. First article in the series, already published. At some point the question comes up: is it worth adding English support? Short answer: yes, and it's less complicated than it looks. Long answer: here's how I did it, with the traps that come with it.

No gettext, no i18n library, no database for translations. Just separate PHP files per language, a restructured JSON file, and three layers of routing. The whole thing fits in a few dozen lines of code spread across files you already have.

Why translate a developer blog

Two concrete reasons, no philosophy.

The English-speaking SEO market is 10 to 50 times larger. A query like "php blog without framework" has a search volume that has nothing to do with the French equivalent. If you write about technical topics that interest English-speaking developers — and you probably do if you're reading this — not having an EN version means missing an existing audience without the overhead being that large once the architecture is in place.

It shows recruiters you're bilingual. A portfolio available in English, with properly written technical content, is a strong signal. No need to mention it in your CV — the site speaks for itself. An international recruiter who lands on your article via Google EN immediately sees that you can work in English.

There's a third reason that's not easy to admit but real: writing the same article in two languages forces you to restructure explanations. It often improves the original version in the process.

Architecture decisions

URL structure

The main constraint: don't break existing URLs. All already-published articles live at /blog/slug. These URLs don't move. English versions live at /en/blog/slug.

/blog/blog-multilingue-php-sans-framework      # FR (default)
/en/blog/blog-multilingue-php-sans-framework   # EN

The /en/ prefix is simple to detect, to generate in links, and to route server-side. No ?lang=en parameter, no cookie, no automatic browser language detection — the URL is the source of truth. This is the only model that works correctly for SEO (search engines index distinct URLs) and respects the principle of least surprise for the user.

One PHP file per language

For each article, two files:

blog/posts/
├── my-slug.php       # French version
└── my-slug.en.php    # English version

The alternative — a single file with translation arrays — looks like this in real life:

<?php
$texts = [
    'fr' => [
        'intro' => 'Ce blog a été construit en PHP pur...',
        'section1' => 'Les choix d\'architecture...',
        // 800 lines of content inside quotes with escaping everywhere
    ],
    'en' => [
        'intro' => 'This blog was built in pure PHP...',
        // 800 more lines
    ],
];
echo $texts[$lang]['intro'];

It's unreadable, unmaintainable, and you spend half your time managing apostrophes and quotes. One file per language is more verbose in terms of file count, but each file is simple to read and modify independently. That's the right trade-off for a blog.

Bonus: if an article doesn't have an English version, the .en.php file simply doesn't exist. The router returns a clean 404. No complex fallback logic needed.

Restructured posts.json

Before adding multilingual support, the JSON was flat:

{
  "slug": "my-slug",
  "date": "2026-03-15",
  "title": "Article title",
  "category": "Lessons learned",
  "tags": ["php", "blog"],
  "excerpt": "Short summary."
}

After migration, language-dependent fields are nested inside fr and en objects:

{
  "slug": "my-slug",
  "date": "2026-03-15",
  "fr": {
    "title": "Titre de l'article",
    "category": "Retour d'expérience",
    "tags": ["php", "blog"],
    "excerpt": "Résumé court."
  },
  "en": {
    "title": "Article title",
    "category": "Lessons learned",
    "tags": ["php", "blog"],
    "excerpt": "Short summary."
  }
}

The date stays at root level — it's language-independent. So is the slug — it's the same for both versions.

Migrating existing data is done with a one-shot PHP script (see below). Don't do it by hand for 30+ articles.

template.php receives $lang

The blog_header() signature already had a $lang parameter set up but unused. It becomes functional:

<?php
function blog_header(
    string $title,
    string $description,
    string $canonical_url,
    ?string $og_image = null,
    ?array $article_data = null,
    string $lang = 'fr'
): void {

This parameter drives: the lang attribute on <html>, og:locale, hreflang tags, breadcrumbs, navigation, and the language toggle. One parameter, no global variable.

The three routing layers

The routing architecture is the trickiest part. It has three layers that must stay consistent with each other, otherwise you end up with a site that works in production but not in development, or vice versa.

Layer 1: .htaccess for Apache

The clean FR blog URLs already existed in .htaccess. The EN addition comes down to two lines:

# Blog EN: /en/blog/slug → blog/posts/slug.en.php
RewriteRule ^en/blog/([a-z0-9-]+)/?$ blog/posts/$1.en.php [L,QSA]

# Blog listing EN: /en/blog/ → blog/index.php with lang=en
RewriteRule ^en/blog/?$ blog/index.php?lang=en [L,QSA]

Two rules. That's it. The existing routing already handles FR URLs. The EN article rule must be added before the FR rules to avoid pattern conflicts — Apache rules apply in declaration order.

Layer 2: router.php for the built-in PHP server

The built-in PHP server (php -S localhost:8000 router.php) doesn't execute .htaccess files. The router.php simulates the same rewrites:

<?php
$uri = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$uri = rtrim($uri, '/');

// EN blog articles
if (preg_match('#^/en/blog/([a-z0-9-]+)$#', $uri, $m)) {
    $file = __DIR__ . '/blog/posts/' . $m[1] . '.en.php';
    if (file_exists($file)) {
        require $file;
        return true;
    }
    // Fallback 404
    http_response_code(404);
    require __DIR__ . '/404.php';
    return true;
}

// EN blog listing
if ($uri === '/en/blog') {
    $_GET['lang'] = 'en';
    require __DIR__ . '/blog/index.php';
    return true;
}

The structure is identical to the Apache logic, translated to PHP. The classic trap here: forgetting to set $_GET['lang'] = 'en' before including index.php. If you test locally and the EN listing displays FR articles, that's where the bug lives.

Layer 3: detection in template.php

The template can receive $lang as a parameter (from articles), but it can also detect the language from the URL (for dynamic pages that don't go through blog_header()):

<?php
// Language detection from URL (fallback if $lang not provided)
function detect_lang(): string {
    $uri = $_SERVER['REQUEST_URI'] ?? '';
    return str_starts_with($uri, '/en/') ? 'en' : 'fr';
}

In practice, articles always pass $lang explicitly. Automatic detection primarily serves the listing and pages that don't have article context.

Template changes

html lang and og:locale

The most visible and simplest change:

<!DOCTYPE html>
<html lang="<?= $lang ?>">
<head>
    ...
    <meta property="og:locale" content="<?= $lang === 'en' ? 'en_US' : 'fr_FR' ?>">

hreflang tags

The hreflang tags tell search engines about alternative versions of a page. They go in the <head> and are generated from the article slug:

<?php if (!empty($article_data['slug'])): ?>
<link rel="alternate" hreflang="fr"
      href="<?= SITE_URL ?>/blog/<?= $article_data['slug'] ?>">
<link rel="alternate" hreflang="en"
      href="<?= SITE_URL ?>/en/blog/<?= $article_data['slug'] ?>">
<link rel="alternate" hreflang="x-default"
      href="<?= SITE_URL ?>/blog/<?= $article_data['slug'] ?>">
<?php endif; ?>

x-default points to the FR version — that's the site's default language. If a user arrives from a country without a localized version, they see FR. Google uses x-default for pages not geographically targeted.

Important: these tags must be reciprocal. The FR page must point to the EN page, and the EN page must point to the FR page. If you miss one direction, Google ignores both.

Adapted breadcrumbs

The breadcrumb changes depending on language — not just the text, but also the URLs:

<?php
$home_url   = $lang === 'en' ? SITE_URL . '/en' : SITE_URL;
$blog_url   = $lang === 'en' ? SITE_URL . '/en/blog' : SITE_URL . '/blog';
$home_label = $lang === 'en' ? 'Home' : 'Accueil';
$blog_label = 'Blog';
?>
<ol class="breadcrumb">
    <li><a href="<?= $home_url ?>"><?= $home_label ?></a></li>
    <li><a href="<?= $blog_url ?>"><?= $blog_label ?></a></li>
    <li class="active"><?= htmlspecialchars($title) ?></li>
</ol>

Language toggle with SVG flags

The navigation toggle shows the flag for the target language (not the current language — the other one). This avoids the paradox of "FR" displayed on a page already in French.

<?php
$toggle_url  = $lang === 'fr'
    ? SITE_URL . '/en/blog/' . ($article_data['slug'] ?? '')
    : SITE_URL . '/blog/'    . ($article_data['slug'] ?? '');
$toggle_lang = $lang === 'fr' ? 'EN' : 'FR';
$toggle_flag = $lang === 'fr' ? '🇬🇧' : '🇫🇷';
// Or SVG inline if emoji rendering is inconsistent
?>
<a href="<?= htmlspecialchars($toggle_url) ?>" class="lang-toggle"
   title="<?= $lang === 'fr' ? 'Read in English' : 'Lire en français' ?>">
    <?= $toggle_flag ?> <?= $toggle_lang ?>
</a>

If you prefer inline SVGs instead of emoji (more reliable on older OS/browsers), here's a compact example:

<?php if ($lang === 'fr'): ?>
<a href="<?= $toggle_url ?>" class="lang-toggle" title="Read in English">
    <svg width="18" height="12" viewBox="0 0 60 40" xmlns="http://www.w3.org/2000/svg">
        <rect width="60" height="40" fill="#012169"/>
        <path d="M0,0 L60,40 M60,0 L0,40" stroke="#fff" stroke-width="8"/>
        <path d="M0,0 L60,40 M60,0 L0,40" stroke="#C8102E" stroke-width="5"/>
        <path d="M30,0 V40 M0,20 H60" stroke="#fff" stroke-width="12"/>
        <path d="M30,0 V40 M0,20 H60" stroke="#C8102E" stroke-width="8"/>
    </svg>
    EN
</a>
<?php else: ?>
<a href="<?= $toggle_url ?>" class="lang-toggle" title="Lire en français">
    <svg width="18" height="12" viewBox="0 0 90 60" xmlns="http://www.w3.org/2000/svg">
        <rect width="30" height="60" fill="#002395"/>
        <rect x="30" width="30" height="60" fill="#EDEDED"/>
        <rect x="60" width="30" height="60" fill="#ED2939"/>
    </svg>
    FR
</a>
<?php endif; ?>

Migrating posts.json: the one-shot script

If you have existing articles with the flat structure, here's the migration script. Run it once from the project root:

<?php
// migrate-posts.php — delete after use
$json = file_get_contents('blog/posts.json');
$posts = json_decode($json, true);

$migrated = [];
foreach ($posts as $post) {
    // Already migrated?
    if (isset($post['fr'])) {
        $migrated[] = $post;
        continue;
    }

    $migrated[] = [
        'slug' => $post['slug'],
        'date' => $post['date'],
        'fr'   => [
            'title'    => $post['title'],
            'category' => $post['category'],
            'tags'     => $post['tags'],
            'excerpt'  => $post['excerpt'],
        ],
        'en'   => [
            'title'    => $post['title'],    // Translate manually
            'category' => $post['category'], // idem
            'tags'     => $post['tags'],
            'excerpt'  => $post['excerpt'],  // idem
        ],
    ];
}

file_put_contents(
    'blog/posts.json',
    json_encode($migrated, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)
);
echo count($migrated) . " articles migrated.\n";

The script copies FR fields into EN as placeholders. You then rework the EN fields manually. Don't forget to delete migrate-posts.php after you're done — it's not an endpoint you want exposed in production.

Blog listing (index.php)

The listing reads posts.json in JavaScript and filters articles by current language. Two main changes.

Reading the current language

// Determine language from URL
const BLOG_LANG = window.location.pathname.startsWith('/en/') ? 'en' : 'fr';

Fetch with absolute path

This is the most common trap. Using a relative path to fetch posts.json:

// ❌ Relative path — PROBLEM on /en/blog/
fetch('posts.json')
  .then(r => r.json())

On /blog/, this fetch resolves to /blog/posts.json — correct. But on /en/blog/, it resolves to /en/blog/posts.json — 404. The file only exists in one place.

// ✅ Absolute path — works from any URL
fetch('/blog/posts.json')
  .then(r => r.json())
  .then(posts => renderPosts(posts, BLOG_LANG));

This was the first bug I hit after deploying the EN listing. Everything worked locally (router.php serves from the root, so relative paths happened to resolve correctly), but broke immediately on the real URL structure. Absolute paths are the only correct answer here.

Language filter in JS

function renderPosts(posts, lang) {
    // Filter articles that have a version in this language
    const filtered = posts.filter(post => post[lang] && post[lang].title);

    filtered.forEach(post => {
        const data = post[lang];
        const url  = lang === 'en'
            ? `/en/blog/${post.slug}`
            : `/blog/${post.slug}`;

        // Build card with data.title, data.excerpt, data.category, data.tags
        renderCard({ ...data, slug: post.slug, date: post.date, url });
    });
}

This means an article without an EN version simply doesn't appear in the EN listing. That's the correct behaviour — it's not a missing feature, it's the expected result of having a .en.php file as the gating condition.

Category filter translation

Category filter buttons change label depending on language. The FR → EN mapping is a simple constant:

// Categories are read dynamically from posts.json
// The labels come from the nested lang object, so no mapping needed:
// post.fr.category = "Retour d'expérience"
// post.en.category = "Lessons learned"
// They're already translated at the data level.

const categories = [...new Set(
    posts
        .filter(p => p[BLOG_LANG])
        .map(p => p[BLOG_LANG].category)
)].sort();

// Dynamically build filter buttons — no hardcoded list
categories.forEach(cat => {
    const btn = document.createElement('button');
    btn.className = 'btn-category';
    btn.dataset.category = cat;
    btn.textContent = cat;
    filterContainer.appendChild(btn);
});

Because category names are stored in posts.json per language, the buttons are already translated at the data level. No extra mapping layer needed.

Sitemap with hreflang

The XML sitemap must declare alternative URLs for each bilingual page. The xhtml namespace is required for xhtml:link tags:

<?php
$posts = json_decode(file_get_contents(__DIR__ . '/posts.json'), true);
header('Content-Type: application/xml; charset=utf-8');
echo '<?xml version="1.0" encoding="UTF-8"?>' . "\n";
?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
<?php foreach ($posts as $post): ?>
    <?php if (!empty($post['fr'])): ?>
    <url>
        <loc><?= SITE_URL ?>/blog/<?= $post['slug'] ?></loc>
        <lastmod><?= $post['date'] ?></lastmod>
        <changefreq>monthly</changefreq>
        <priority>0.8</priority>
        <xhtml:link rel="alternate" hreflang="fr"
                    href="<?= SITE_URL ?>/blog/<?= $post['slug'] ?>"/>
        <?php if (!empty($post['en'])): ?>
        <xhtml:link rel="alternate" hreflang="en"
                    href="<?= SITE_URL ?>/en/blog/<?= $post['slug'] ?>"/>
        <xhtml:link rel="alternate" hreflang="x-default"
                    href="<?= SITE_URL ?>/blog/<?= $post['slug'] ?>"/>
        <?php endif; ?>
    </url>
    <?php endif; ?>
    <?php if (!empty($post['en'])): ?>
    <url>
        <loc><?= SITE_URL ?>/en/blog/<?= $post['slug'] ?></loc>
        <lastmod><?= $post['date'] ?></lastmod>
        <changefreq>monthly</changefreq>
        <priority>0.7</priority>
        <xhtml:link rel="alternate" hreflang="fr"
                    href="<?= SITE_URL ?>/blog/<?= $post['slug'] ?>"/>
        <xhtml:link rel="alternate" hreflang="en"
                    href="<?= SITE_URL ?>/en/blog/<?= $post['slug'] ?>"/>
        <xhtml:link rel="alternate" hreflang="x-default"
                    href="<?= SITE_URL ?>/blog/<?= $post['slug'] ?>"/>
    </url>
    <?php endif; ?>
<?php endforeach; ?>
</urlset>

EN article priority (0.7) is slightly lower than FR articles (0.8) — the site defaults to French, FR articles are the source of truth. It's a convention, not a strict rule.

What you don't need

List of things I considered and decided against:

An i18n library (gettext, Symfony Translation, etc.) — For a blog, interface strings fit on two hands: "Read more", "Home", "min read". Two ternary operators in the template is sufficient. An i18n library with .po or .yaml files would be pure over-engineering.
Automatic language detection — Detecting Accept-Language and redirecting automatically is a bad idea. It breaks link sharing, surprises users, and causes indexation problems. The URL is the source of truth.
Database for translations — If your content is PHP files, your translations are PHP files. Architectural consistency has value in itself.
A single file with switch($lang) — Covered above. Unreadable once articles go past 200 lines.
Automatic translation (DeepL API, etc.) — Technically possible. But a technically dense blog article translated automatically is obvious to any developer. And it doesn't convince a recruiter that you can work in English. If the goal is demonstrating bilingualism, you actually have to write in English.

Summary of changed files

For an already-running blog, the exhaustive list of changes:

.htaccess — 2 RewriteRule lines for EN URLs
router.php — 2 corresponding PHP routing blocks
blog/template.php — blog_header() uses $lang for html[lang], og:locale, hreflang, breadcrumbs, nav, toggle; blog_footer() receives $lang to filter related articles
blog/posts.json — migrated to nested fr/en structure (one-shot script)
blog/index.php — absolute fetch /blog/posts.json, BLOG_LANG detection from URL, language filter, adapted URLs
blog/sitemap.php — added xhtml namespace and xhtml:link tags
For each existing article: blog/posts/slug.en.php to create

No new configuration files, no new dependencies, no stack change. All modifications are localized in files you're already maintaining.

In practice

This blog has been running with this architecture since the restructuring. Existing FR URLs haven't moved — no redirects to manage, no impact on already-indexed articles' rankings. EN versions are indexable as soon as they're created.

The only real cost is writing time: translating a 1000-word article takes between 30 minutes and an hour depending on technical density. That's the cost that can't be compressed — not the architecture.

If you already have a PHP blog without a framework and you're hesitating to add bilingual support because you think it's complex: the code isn't the hard part.

PHP blog SEO: JSON-LD, ToC and crawlable pagination

Odilon HUGONNOT — Mon, 11 May 2026 09:00:03 +0000

Google Search Console showed zero indexed articles after three weeks of publishing. The articles existed. The URLs returned 200. The sitemap had been submitted. The problem was elsewhere: the blog listing loaded posts.json via fetch(), then rendered all the HTML in JavaScript. As far as Googlebot was concerned, the page was an empty shell with a spinner.

What follows is the set of fixes applied to the shared PHP template — no framework, no build step, plain Apache. Each point has a concrete reason, not just "SEO best practices say so".

The JS-first problem

Googlebot can execute JavaScript. Google has been saying this for years, and it's true. But "can" doesn't mean "systematically" or "immediately". JS crawling goes through a secondary rendering queue — plain HTML pages are indexed first. The result: a fully JS-rendered blog can take weeks to get indexed, and even then, only if Googlebot decides the page is worth the rendering cost.

The second problem is structural: if pagination is handled entirely in JS (click "Page 2" → client-side re-render), page 2 doesn't exist from a crawler's perspective. There's only one URL, and it always shows the first 10 articles. Googlebot doesn't click JavaScript buttons to see more content. Articles on page 3 or 4 will never be crawled.

The fix is straightforward in principle: the server must render the HTML for articles on the current page. JavaScript can then take over for interactive navigation — but the first render must be visible in the page source.

JSON-LD and articleBody: what Google actually wants

Schema.org BlogPosting is the baseline structured data for a blog article. It lets Google display the date, author, and potentially the breadcrumb in rich results. But the most useful field is articleBody: it's the plain text of the article, which Google uses for featured snippets.

The problem: when JSON-LD is generated inside blog_header() (at the top of the page), the article content hasn't been rendered yet. You can't inject articleBody at that point.

The solution is PHP output buffering. In blog_header(), start a buffer and put a placeholder in the JSON-LD:

ob_start();
// JSON-LD with placeholder
$json_ld = '{ "@type": "BlogPosting", "articleBody": "ARTICLE_BODY_PLACEHOLDER", ... }';

Then in blog_footer(), retrieve the full rendered HTML, extract the content of the .article-content div, strip the tags, and inject the text in place of the placeholder before sending everything to the browser:

// In blog_footer() — capture the HTML rendered by the article
$article_html = ob_get_clean();

if (preg_match('/

The complete JSON-LD is injected into <head> just before the buffer is sent. Google sees a real articleBody, not a placeholder. The 5000-character limit is arbitrary — Google truncates anyway.

Server-side ToC and the iconv trap

A server-side table of contents has two advantages: it's visible in the page source (therefore crawlable), and it has no JavaScript dependency. The implementation is straightforward — parse the <h2> and <h3> tags from the article HTML, generate anchors, and inject the ToC at the beginning of .article-content.

The classic trap is generating anchor IDs for headings with accented characters. The standard reflex is to use iconv for transliteration:

// ❌ Depends on system locale — returns empty string on servers without fr_FR.UTF-8
$id = preg_replace('/[^a-z0-9]+/', '-', strtolower(iconv('UTF-8', 'ASCII//TRANSLIT', $heading_text)));

On a server where the fr_FR.UTF-8 locale isn't installed, iconv with //TRANSLIT returns an empty string for accented characters. The generated anchor becomes #--- instead of #les-3-pieges. The ToC link points to nothing.

The fix is an explicit mapping with strtr():

// ✅ Explicit mapping, portable
$id = preg_replace('/[^a-z0-9]+/', '-', strtolower(strtr($heading_text, [
    'à'=>'a','â'=>'a','é'=>'e','è'=>'e','ê'=>'e','ë'=>'e',
    'î'=>'i','ï'=>'i','ô'=>'o','ù'=>'u','û'=>'u','ü'=>'u',
    'ç'=>'c','æ'=>'ae','œ'=>'oe',
])));

No locale dependency. No unpredictable behavior between dev and production. The same heading always generates the same ID. The same pattern is applied both to the <h2> IDs in the article body and to the links in the ToC — consistency guaranteed.

Crawlable pagination: the hybrid approach

The goal is for Googlebot to reach every article, not just those on the first page. The constraint: don't break the existing interactive navigation (search, category filters, click-through pagination).

The hybrid solution: PHP loads posts.json and renders the cards for the current page (determined by the ?page=N query parameter). JavaScript keeps its search and filter functions, but detects whether PHP has already rendered content on initial load — and if so, skips the re-render.

<?php foreach ($page_posts as $post):
    $meta = $post[$lang];
    $url = $base_url . $post['slug'];
?>
<article class="blog-card" data-slug="<?= htmlspecialchars($post['slug']) ?>">
    <h2 class="blog-card-title">
        <a href="<?= htmlspecialchars($url) ?>"><?= htmlspecialchars($meta['title']) ?></a>
    </h2>
    ...
</article>
<?php endforeach; ?>

Pagination links are real <a href="?page=2"> elements, with a data-page attribute so JavaScript can intercept them:

document.querySelectorAll('a[data-page]').forEach(function(link) {
    link.addEventListener('click', function(e) {
        e.preventDefault();
        currentPage = parseInt(this.dataset.page);
        render(filterPosts());
        window.history.pushState({}, '', '?page=' + currentPage);
    });
});

To prevent JS from re-rendering cards that PHP just rendered, add a guard at initial load:

// If no active filter and PHP already rendered articles, skip re-render
var hasPhpContent = document.querySelector('#posts-container article') !== null;
if (searchTerm || (activeCategory !== 'Tous' && activeCategory !== 'All') || !hasPhpContent) {
    render(filterPosts());
}

Googlebot crawls /blog/?page=2, sees the cards in plain HTML, follows the links to individual articles. JavaScript is no longer a prerequisite for indexation. For the user, nothing changes — navigation stays instant.

hreflang, canonical, og:type: the details that matter

These three are often treated as copy-paste boilerplate. Each has a specific purpose.

The canonical must point to the URL without a query string. Without it, /blog/my-article?page=1 and /blog/my-article are two distinct URLs as far as Google is concerned, and it doesn't know which one to index. One line is enough:

$canonical = strtok($current_url, '?');

The hreflang links tell Google that French and English versions of the same content exist. Without them, Google may decide to show the wrong version based on the visitor's language. The x-default is mandatory — it specifies which version to show when no locale matches (typically a Japanese user on a FR/EN blog):

<link rel="alternate" hreflang="fr" href="https://www.web-developpeur.com/blog/" />
<link rel="alternate" hreflang="en" href="https://www.web-developpeur.com/en/blog/" />
<link rel="alternate" hreflang="x-default" href="https://www.web-developpeur.com/blog/" />

The og:type should be article on article pages, and website on the listing and homepage. The distinction affects how Facebook and LinkedIn generate the share preview. og:locale is complementary — fr_FR vs en_US depending on the article language.

Conclusion

None of these changes required rethinking the blog's architecture. Everything lives in the shared PHP template, with a minor adjustment to the listing page JavaScript. No SSR framework, no build step, no dedicated CDN.

The most counter-intuitive part is the output buffering for articleBody: it's a technique from the early 2000s that neatly solves a sequencing problem between a template's header and footer. Same for the strtr() mapping — it's less "elegant" than iconv, but it's what actually works in production.

Two weeks after deploying these changes, Search Console was showing the first indexed articles. Not because Google had suddenly decided to crawl JavaScript better — but because the HTML was finally there, visible from the very first byte of the response.

Dynamic related articles in PHP without a database

Odilon HUGONNOT — Sun, 10 May 2026 09:00:03 +0000

The "related articles" section at the bottom of a blog post is exactly the kind of thing you hardcode at first — two links picked by hand — and then forget to maintain. The result: stale suggestions pointing to unrelated articles, or worse, articles that no longer exist.

On this blog, all content is described in a single posts.json file, with each article's slug, category, and tags. That's enough to automatically calculate relevant suggestions without a database.

The problem with hardcoded links

The initial version passed an array of links to blog_footer():

<?php blog_footer([
    ['url' => '/blog/commentaires-sans-bdd-php', 'title' => 'Adding comments...'],
    ['url' => '/blog/creer-un-blog-avec-claude-code', 'title' => 'Building a blog...'],
]); ?>

Functional, but requires manual maintenance in every article file. With 10 articles it's manageable, with 50 it becomes unworkable — and it never automatically improves when you publish a new article that would be more relevant.

The source of truth: posts.json

Each article is described in posts.json with its metadata:

{
  "slug": "analytics-php-sans-cookies-rgpd",
  "title": "Analytics PHP sans cookies ni base de données",
  "date": "2026-02-25",
  "category": "Retour d'expérience",
  "tags": ["php", "analytics", "rgpd", "sécurité", "no-database"]
}

This is already used for the blog listing and the sitemap. Might as well use it for suggestions too.

The scoring algorithm

The principle is straightforward: for each candidate article (all articles except the current one), we calculate a relevance score based on two criteria:

+2 per shared tag — tags are the most precise signal
+1 if same category — a broader contextual signal

We sort by descending score, break ties by most recent, and keep the top 3. Articles with a score of 0 (nothing in common) are excluded.

function find_related_posts(string $slug, int $limit = 3): array {
    $all = json_decode(file_get_contents(__DIR__ . '/posts.json'), true) ?? [];

    // Find the current article
    $current = null;
    foreach ($all as $p) {
        if ($p['slug'] === $slug) { $current = $p; break; }
    }
    if (!$current) return [];

    $current_tags = $current['tags'] ?? [];
    $current_cat  = $current['category'] ?? '';

    // Score the candidates
    $scored = [];
    foreach ($all as $p) {
        if ($p['slug'] === $slug) continue;

        $score = count(array_intersect($current_tags, $p['tags'] ?? [])) * 2
               + ($p['category'] === $current_cat ? 1 : 0);

        if ($score > 0) {
            $scored[] = ['score' => $score, 'post' => $p];
        }
    }

    // Sort by score desc, then date desc on ties
    usort($scored, fn($a, $b) =>
        $b['score'] <=> $a['score'] ?: strcmp($b['post']['date'], $a['post']['date'])
    );

    return array_map(fn($s) => [
        'url'   => '/blog/' . $s['post']['slug'],
        'title' => $s['post']['title'],
    ], array_slice($scored, 0, $limit));
}

Integration in blog_footer()

blog_footer() already accepted a $slug parameter (used to load comments). It just needs to auto-trigger the calculation when no explicit list is passed:

function blog_footer($related_posts = [], $slug = null) {
    if (empty($related_posts) && $slug !== null) {
        $related_posts = find_related_posts($slug);
    }
    // ...
}

On the article side, the call becomes:

<?php blog_footer([], 'my-article-slug'); ?>

That's it. Existing articles that were already passing their slug didn't need to be modified — they inherit the automatic behavior.

Why weight tags x2

A category groups articles with similar context but not necessarily similar subjects — "Lessons learned" can cover PHP just as well as Bash. Tags are more precise: two articles sharing the tags php and no-database are probably discussing the same problem. The x2 weighting on tags ensures that topical proximity takes precedence over categorical proximity.

Limitations

The posts.json file is read on every article page load. On a low-traffic blog with a dozen articles, this is negligible. If volume grows, a simple opcache or file cache would be sufficient — but that's not today's problem.

The algorithm doesn't consider the actual content of the articles, only their metadata. The quality of suggestions therefore depends directly on the quality of the tagging. Which is a good reason to be deliberate with tags rather than slapping them on at random.

PHP analytics without cookies or database — and without violating GDPR

Odilon HUGONNOT — Sat, 09 May 2026 09:00:01 +0000

I wanted to know which pages of my portfolio are visited, where the traffic comes from, and whether anyone actually reads the blog — without plugging in Google Analytics, without setting up a database, without displaying a cookie banner. The constraint: Apache + pure PHP hosting, nothing else.

Why not Google Analytics

GA4 would have taken 5 minutes. But two concrete problems:

GDPR: the moment you use GA, personal data (IP, behavior) goes to Google. Legal obligation to display a consent banner, handle refusals, maintain a processing register. For a personal portfolio, that's disproportionate.
Blocked: uBlock Origin, Brave, Firefox Enhanced Tracking Protection — GA is blocked by a significant portion of developers who are precisely my audience. The stats would be underreported.

Self-hosted alternatives like Umami or Plausible require Node.js + PostgreSQL. Not available here.

The solution: file log, hashed IP, zero cookies

A tracker.php file included at the top of each page. It writes a line to logs/visits.tsv on every visit. That's it.

The real value is in the security decisions:

1. No cookies set — therefore no consent required

GDPR mandates consent only when storing personal data on the user's side (cookies) or when identifying a natural person. None of that here. The server records a line and that's it — the user is unaware, feels nothing, and it's legal.

2. IP anonymized before storage

An IP address is personal data under GDPR. We never store it in plain text. Instead, we compute a salted SHA-256 hash, truncated to 16 characters:

$ip_hash = substr(
    hash('sha256', ($_SERVER['REMOTE_ADDR'] ?? '') . 'cv_salt_xK9!2026'),
    0, 16
);

The salt makes the hash irreversible even with a rainbow table. The result allows counting unique visitors without ever being able to recover the original IP. This is exactly what France's CNIL recommends for the consent exemption.

3. Bot filtering upfront

Without filtering, the log file grows quickly with useless traffic — Google crawlers, Bing, scrapers, monitoring tools. A regex on the User-Agent eliminates the majority:

if (preg_match('/bot|crawl|spider|slurp|wget|curl|libwww|python|java|Go-http/i', $ua)) {
    return; // Exit immediately, nothing is logged
}

This doesn't catch bots that disguise themselves as humans, but it covers 95% of real automated traffic.

4. Logs directory inaccessible from the web

The visits.tsv file contains IP hashes, URLs, and timestamps. Even anonymized, it must not be publicly accessible. A .htaccess in the logs/ directory is sufficient:

Deny from all

Apache blocks any HTTP request to this directory. PHP on the server can still write to it internally — only browser access is blocked.

5. Isolated variables to avoid polluting the global scope

The tracker is included via require in index.php, so it shares the same PHP scope. To avoid overwriting existing variables or exposing internal data, all tracker variables are prefixed with $_ and deleted with unset() at the end of the script. It's rudimentary but effective without having to encapsulate everything in a function.

The dashboard

A password-protected stats.php reads the TSV file, calculates KPIs, and displays them with Chart.js (CDN). No complex persistent session — just a standard PHP $_SESSION and a plaintext password comparison (acceptable for a purely local/admin access on a personal portfolio).

KPIs displayed:

Total visits and unique visitors over 7 / 30 / 90 days
Visits today vs yesterday
Visits-per-day chart
Top pages visited
Traffic sources (direct / external / internal navigation)
Desktop / mobile / tablet breakdown
Hourly visit heatmap

What it doesn't do

No heatmaps, no funnels, no reconstructed sessions, no visit duration. For a portfolio, that level of detail is pointless. What matters: are people arriving, and which pages are they looking at.

The log file will grow. It will need periodic purging or log rotation (one file per month, for example). For now, a 100,000-line log weighs about 8 MB — PHP reads it in under a second.

Result

Zero cookies. Zero consent banner. Zero external production dependencies. Zero identifiable personal data stored. Functional dashboard in under 200 lines of PHP.

That's the right level of complexity for the actual need.

[

stats.php in production — KPIs, visits/day, top pages, devices, hourly heatmap. Click to enlarge.

](https://www.web-developpeur.com/assets/images/stats.jpg "View full size")

Cache-busting JSON in PHP with filemtime

Odilon HUGONNOT — Fri, 08 May 2026 09:00:01 +0000

The blog listing loads articles via fetch('posts.json'). Problem: the browser caches this file. When you publish a new article, visitors keep seeing the old list until they manually clear their cache — which they never do.

Why the browser caches the JSON

Without an explicit Cache-Control directive, Apache applies a heuristic: it estimates a cache duration from the file's Last-Modified header. In practice, browsers can keep the file cached for several hours, or even several days depending on their own rules.

You could solve this server-side with an HTTP header:

<FilesMatch "posts\.json$">
    Header set Cache-Control "no-cache, must-revalidate"
</FilesMatch>

But this requires mod_headers to be enabled on Apache — which isn't guaranteed on shared hosting. And a systematic no-cache forces a server round-trip on every page load, even when the file hasn't changed.

The solution: filemtime as a query param

The principle of query string cache-busting is simple: as long as the URL doesn't change, the browser serves from its cache. As soon as the URL changes, it refetches.

Inject the file's last-modified timestamp via PHP:

fetch('posts.json?v=<?php echo filemtime(__DIR__ . "/posts.json"); ?>')

filemtime() returns a Unix integer — the timestamp of the file's last modification on disk. The result in the generated HTML:

fetch('posts.json?v=1740268800')

As soon as you modify posts.json (adding an article, fixing an excerpt), the timestamp changes, the URL changes, the browser treats it as a new resource and refetches. Between two publications, the URL is identical → the cache is used, no unnecessary request.

Why this is better than no-cache

With Cache-Control: no-cache, the browser must query the server on every visit to check whether the file has changed (conditional request with If-Modified-Since). It's fast, but it's still a network round-trip.

With query string cache-busting, if the file hasn't changed since the last visit, the URL is exactly the same — the browser serves from its local cache, with no network request at all. It's more aggressive in the right way: you benefit from the cache when possible, bypass it only when necessary.

The same technique for CSS and JS assets

This is exactly the principle used by all modern bundlers (Vite, Webpack) that generate filenames with hashes: main.a3f9c2.js. Here there's no build, but filemtime() plays the same role without any infrastructure:

<link rel="stylesheet" href="assets/css/styles.css?v=<?php echo filemtime(__DIR__ . '/assets/css/styles.css'); ?>">
<script src="assets/js/main.js?v=<?php echo filemtime(__DIR__ . '/assets/js/main.js'); ?>"></script>

Browsers and CDNs ignore the query string for cache matching in some configurations, but for a standard Apache setup serving files directly, it works reliably across all modern browsers.

Limitation: intermediate proxies

Some proxies and CDNs (Cloudflare in aggressive mode, Varnish by default) ignore the query string and serve the same cached version regardless of the ?v= value. In that case, filename-based cache-busting (hash in the filename) is more robust. For a portfolio served directly by Apache with no CDN, this isn't an issue.