content-design-system

Content Design System

Generate a complete, opinionated visual system for web content — from typographic scale to styled content blocks — adapted to the project's ambiance and content type.

Why This Skill Exists

The three most common failures in AI-generated web content layouts:

1. Flat hierarchy — heading levels too close in size/weight, no visual landmarks
2. Invisible content blocks — citations, callouts, code look like body text with a border
3. Hostile readability — line length, spacing, contrast make extended reading painful

This skill prevents all three by enforcing measurable rules at every step.

Reference files

• references/content-blocks.md — Detailed CSS specs for all 7 content block types (citations, callouts, code, tables, lists, alerts, examples). Read this file before generating Step 3 output.

---

Step 0 — Project Brief

Before generating anything, establish the project context. Ask the user if missing.

## Brief du projet
- Type de contenu     : [long-form / vitrine / hybride]
- Ambiance cible      : [ex. dark fantasy / éditorial / SaaS / corporate]
- Inspirations        : [ex. Stripe docs, A24, Notion, iA Writer]
- Thème               : [clair / sombre / les deux]
- Framework CSS       : [aucun / Tailwind / Bootstrap / autre]
- Polices souhaitées  : [ex. Inter + Literata / system fonts / à proposer]
- Contenu enrichi     : [citations / callouts / code / tableaux / listes / alertes / exemples]
- Densité cible       : [aéré / compact / variable]

Si non fourni : inférer du contexte, proposer le brief rempli, attendre validation.

Adaptation au type de contenu :

• Long-form → largeur ≤ 68ch, rythme vertical serré, échelle Major Third (1.25) ou Perfect Fourth (1.333)
• Vitrine → titres plus grands (ratio ≥ 1.5), espacement dramatique entre zones
• Hybride → deux modes : .hero (vitrine) et .prose (long-form) avec transition fluide

---

Step 1 — Échelle Typographique

L'échelle typographique est la colonne vertébrale. Tout le reste en découle.

Choisir le ratio

Ratio	Nom	Effet	Usage idéal
1.125	Major Second	Subtil, compact	Dashboards, UI dense
1.200	Minor Third	Équilibré	Docs techniques
1.250	Major Third	Lisible, confortable	Blogs, articles
1.333	Perfect Fourth	Expressif, aéré	Éditorial, magazines
1.500	Perfect Fifth	Dramatique	Landing pages, héros
1.618	Golden Ratio	Très dramatique	Sites artistiques

Règles critiques :

• Ne jamais utiliser ratio < 1.2 pour du contenu à lire
• Ne jamais descendre sous 1.333 pour les sites vitrines

Générer l'échelle

À partir du ratio et d'une base (min 1rem / 16px) :

body    = base                h4 = base × ratio^3
h6      = base × ratio^1     h3 = base × ratio^4
h5      = base × ratio^2     h2 = base × ratio^5
                              h1 = base × ratio^6
                              display = base × ratio^7  (optionnel, héros)

Vérifications obligatoires :

• h1/body ≥ 2.0 — sinon augmenter le ratio
• h6 ≥ taille du body
• Chaque paire adjacente perceptiblement différente

Différenciation multi-signal

La taille seule ne suffit pas. Chaque heading se différencie sur ≥ 2 axes :

Niveau	Axes recommandés
h1	Taille + bold + letter-spacing serré (-0.02em) + font optionnelle
h2	Taille + semibold + border-bottom ou couleur accent
h3	Taille + semibold + text-transform ou couleur muted
h4	Taille + medium + italic ou small-caps
h5	Taille ≈ body + bold + uppercase + letter-spacing élargi
h6	Taille ≈ body + semibold + couleur muted

Anti-pattern : h2 et h3 ne diffèrent QUE par 2px → indistinguables. Ajouter un signal supplémentaire.

Espacement vertical des headings

/* margin-top ≥ 2× margin-bottom → association visuelle titre → contenu */
h1 { margin-top: 0;      margin-bottom: 1.5rem; }
h2 { margin-top: 3.5rem; margin-bottom: 1rem;   }
h3 { margin-top: 2.5rem; margin-bottom: 0.75rem;}
h4 { margin-top: 2rem;   margin-bottom: 0.5rem; }
h5 { margin-top: 1.5rem; margin-bottom: 0.5rem; }
h6 { margin-top: 1.5rem; margin-bottom: 0.5rem; }

Output attendu

Bloc CSS complet avec toutes les tailles en rem, line-height adapté (tight pour grands titres, normal pour petits), font-weight, letter-spacing, font-family par niveau, marges verticales, commentaires avec le ratio et la logique de différenciation.

---

Step 2 — Rythme Vertical & Espacement

Unité de base

:root {
  --rhythm: 1.7rem;  /* line-height body (1.7) × font-size (1rem) */
}

Tous les espacements sont des multiples de cette unité.

Règles d'espacement

Transition	Espacement	Justification
p → p	1× rhythm	Séparation standard
heading → p	0.5× rhythm	Titre lié au contenu qui suit
p → heading	2–3× rhythm	Rupture de section, respiration
p → blockquote/callout/code	1.5× rhythm	Distinguer du flux
blockquote/callout → p	1.5× rhythm	Retour au flux
p → liste	1× rhythm	Continuité naturelle
section → section	3–4× rhythm	Rupture majeure
section → section (vitrine)	4–6× rhythm	Respiration dramatique

Long-form vs vitrine

• Long-form : rythme serré (1×–2×), priorité à la continuité de lecture
• Vitrine : rythme ouvert (2×–4×), priorité à l'impact par section
• Hybride : classe conteneur (.prose vs .hero) pour basculer

---

Step 3 — Content Blocks

→ Lire references/content-blocks.md avant de générer cette section.

Chaque bloc de contenu enrichi doit avoir une identité visuelle propre qui le distingue immédiatement du texte courant.

Principe directeur : un content block se différencie du body text sur ≥ 3 axes visuels parmi : fond, bordure, padding, typographie, icône, couleur, indentation, ombre.

Les 7 types couverts

Type	Rôle	Signal visuel principal
Citation	Propos rapporté, extrait	Border-left + italic + fond subtil
Callout	Information contextuelle	Border-left colorée + icône + fond
Code	Contenu technique exécutable	Font mono + fond contrasté + border
Tableau	Données structurées comparables	Header distinct + bandes alternées
Liste	Énumération ordonnée ou non	Puces custom + espacement généreux
Alerte	Message transitoire/actionnable	Fond coloré + icône + dismiss button
Exemple	Démo visuelle avec source	Zone preview + zone code + caption

Silhouette test : un lecteur qui scrolle rapidement doit pouvoir identifier chaque type de bloc sans lire le contenu. Si deux types se ressemblent visuellement, ils manquent de différenciation.

Règles transversales

• Les callouts se distinguent entre eux par couleur ET icône (jamais couleur seule)
• Le thead des tableaux diffère du tbody sur ≥ 2 signaux
• Le code inline ne doit pas être confondu avec un lien (pas de soulignement, couleur différente)
• Les alertes vs callouts : les alertes sont dismissible et/ou hors du flux ; les callouts sont dans le flux éditorial

---

Step 4 — Conteneur Prose

Le wrapper .prose applique toutes les règles sur un bloc de contenu.

.prose {
  max-width: var(--content-max-width, 68ch);
  margin-inline: auto;
  font-family: var(--font-body);
  font-size: var(--text-base);
  line-height: var(--leading-body, 1.7);
  color: var(--color-text);

  & > * + * { margin-top: 1.25em; }

  & hr {
    border: none;
    border-top: 1px solid var(--color-border);
    margin: 3em auto;
    max-width: 5em;
  }

  & a {
    color: var(--color-primary);
    text-decoration: underline;
    text-underline-offset: 2px;
    text-decoration-thickness: 1px;
    transition: color var(--duration-base) var(--ease-default);
    &:hover { text-decoration-thickness: 2px; }
  }

  & img { max-width: 100%; height: auto; border-radius: var(--radius-md); margin: 1.5em 0; }

  & figure {
    margin: 2em 0;
    & figcaption {
      margin-top: 0.5em;
      font-size: var(--text-sm);
      color: var(--color-text-muted);
      text-align: center;
    }
  }
}

/* Variante vitrine */
.prose--hero {
  max-width: 80ch;
  font-size: var(--text-lg);
  & > * + * { margin-top: 2em; }
}

---

Step 5 — Adaptation Framework

• Vanilla CSS → custom properties dans :root + règles CSS classiques
• Tailwind → extensions dans tailwind.config.js (theme.extend) + @layer components avec @apply. Les tokens deviennent des entrées du config, pas des classes arbitraires
• Bootstrap → overrides de variables Sass ($font-size-base, $headings-*, $spacer) + CSS custom pour les composants non couverts

---

Step 6 — Checklist de Livraison

## Checklist Content Design System

### Échelle typographique
- [ ] Ratio choisi et documenté
- [ ] h1/body ≥ 2.0×
- [ ] Chaque paire adjacente diffère sur ≥ 2 axes
- [ ] h6 ≥ taille du body
- [ ] line-height adapté par niveau

### Rythme vertical
- [ ] Unité de base définie (--rhythm)
- [ ] margin heading→content < margin content→heading
- [ ] Espacement entre sections ≥ 3× rhythm
- [ ] Mode long-form ET vitrine couverts (si hybride)

### Content blocks
- [ ] Chaque bloc se distingue du body sur ≥ 3 axes visuels
- [ ] Silhouette test passé
- [ ] Callouts : couleur + icône par type sémantique
- [ ] Code : inline et bloc différenciés, overflow-x géré
- [ ] Tableaux : thead distinguable, responsive wrapper
- [ ] Listes : espacement inter-items ≥ 0.4em
- [ ] Tokens sémantiques (info, warning, danger, success)
- [ ] Thème sombre vérifié (si applicable)

### Conteneur prose
- [ ] max-width ≤ 70ch
- [ ] line-height ≥ 1.6
- [ ] Liens avec underline visible + hover
- [ ] Images responsives

---

Notes pour l'agent

1. Toujours commencer par l'échelle typographique. C'est la fondation.
2. Calculer, ne pas improviser. Chaque taille de heading = calcul depuis le ratio.
3. Produire du CSS exécutable, pas du pseudo-code. Copié-collé dans un projet réel.
4. Adapter au framework (voir Step 5).
5. Proposer des variantes pour citations et callouts (au moins 2 options stylistiques).
6. Silhouette reconnaissable — chaque type de bloc a une forme visuelle distincte.
7. Vérifier le thème sombre — les background subtils du clair deviennent souvent invisibles en dark.
8. Plus de drame pour les vitrines — ratio plus élevé, espacement plus généreux.