station

S4 · Spec design

playbook/S4-spec-design.md

S4 — Spec & Design System (J5–6)

Objectif : figer 3 features et pas une de plus + un design system suffisant pour que S5 ne s'interroge plus sur "comment ça doit ressembler". Le scope est en béton à la fin de J6.

Durée

2 journées (J5 = spec produit ; J6 = design tokens + wireframes).

Inputs

  • One-pager S1 + ICP narrow
  • Unfair angle + positioning gap S2
  • Nom validé + domaine acheté S3
  • playbook/taste.md (refs Linear/Stripe/Vercel/Mercury, anti-patterns)

Output (livrables verrouillés)

  • runs/{sprint}/04-spec.md — spec produit narrative + user stories
  • runs/{sprint}/04-design-tokens.json — palette / typo / motion / radius
  • runs/{sprint}/wireframes/ — 5 écrans clés (PNG ou HTML pretext via skill design-html)
  • Section s4_spec dans startup.json
  • 📱 Gate Telegram : approval Martin sur scope 3 features + tokens

Critères de verrouillage (TOUS requis)

  1. Exactement 3 features v1 documentées. Pas 2 (sous-spec), pas 4 (over-scope). 3.
  2. Pour chaque feature : user story + 3–5 acceptance criteria testables (un humain peut dire si c'est passé ou pas).
  3. Liste "OUT OF SCOPE v1" écrite — 10–20 features explicitement retirées. C'est le pendant essentiel des 3 features incluses ; sans cette liste, le scope creep est garanti.
  4. Design tokens versionnés : palette (3-5 couleurs), typo (1-2 fonts + scale), motion (1-2 easings + durées), radius (3 valeurs), spacing (échelle 4/8px).
  5. 5 wireframes clés : login → onboarding → main view → settings → upgrade (Stripe checkout). Format peu importe (Figma export PNG, HTML pretext, schéma Mermaid) — l'important c'est que S5 sache quoi coder.
  6. Approval Telegram Martin : message envoie les 3 features + 1 phrase "out of scope" + screenshot palette. Réponse binaire GO/REVOIR.

Process

J5 matin — Ruthless scoping (3h)

  1. Lister 10 features auxquelles tu penses. Les écrire sans filtre.
  2. Pour chacune, répondre :
    • Sans cette feature, le produit délivre-t-il toujours sa promesse core (one-pager S1) ? Si OUI → "out of scope".
    • Cette feature dépend-elle d'une autre feature ? Si OUI → ne peut pas être en v1 standalone.
    • Cette feature requiert-elle > 1 journée de S5 ? Si OUI → suspect, reformuler en plus petit.
  3. Garder les 3 features qui satisfont : essentielles + indépendantes + < 1 jour de build chacune.
  4. Écrire la "out of scope list" — les 7+ autres explicitement.

J5 après-midi — User stories + acceptance criteria (3h)

Pour chaque feature :

## Feature 1 — {Nom}

**User story** : En tant que [ICP], quand [trigger contextuel], je [action], pour [outcome mesurable].

**Acceptance criteria** :
- [ ] AC1 : {test pass/fail testable par un humain en 30 sec}
- [ ] AC2 : ...
- [ ] AC3 : ...
- [ ] AC4 (edge case) : ...
- [ ] AC5 (security/RGPD si applicable) : ...

**Out of scope (relié) v2** : {1-2 sous-features qui apparaîtront naturellement en v2}

J6 matin — Design tokens (2h)

Inspirations canonisées dans playbook/taste.md. Pour ce sprint, choisir 1 ref primaire (ex: Linear pour B2B SaaS dev-conscient, Mercury pour fintech, Cuely pour AI-first agent, Stripe pour pricing-as-marketing).

{
  "palette": {
    "background": "#0A0A0B",
    "foreground": "#FAFAFA",
    "muted": "#71717A",
    "accent_primary": "#...",
    "accent_destructive": "#EF4444",
    "border": "#27272A"
  },
  "typography": {
    "font_sans": "Inter",
    "font_mono": "JetBrains Mono",
    "scale": {
      "xs": "12px / 16px",
      "sm": "14px / 20px",
      "base": "16px / 24px",
      "lg": "18px / 28px",
      "xl": "24px / 32px",
      "2xl": "32px / 40px",
      "3xl": "48px / 56px"
    }
  },
  "motion": {
    "ease_standard": "cubic-bezier(0.2, 0, 0, 1)",
    "ease_decel": "cubic-bezier(0, 0, 0, 1)",
    "duration_fast": "120ms",
    "duration_base": "200ms",
    "duration_slow": "320ms"
  },
  "radius": {
    "sm": "4px",
    "md": "8px",
    "lg": "12px",
    "full": "9999px"
  },
  "spacing": { "scale": [0, 4, 8, 12, 16, 24, 32, 48, 64, 96, 128] }
}

J6 après-midi — Wireframes 5 écrans (3h)

Les 5 écrans canoniques d'un SaaS B2B :

  1. Login / signup : email + magic link OU Google OAuth. Pas de mot de passe.
  2. Onboarding : 3 étapes max. Récolter le minimum pour rendre la value visible immédiatement.
  3. Main view : le hero feature qui justifie l'abo. Doit produire un "wow" en < 60 sec.
  4. Settings : profil + billing (lien vers Stripe Customer Portal) + integrations.
  5. Upgrade / Stripe checkout : pricing page → click → Stripe Checkout hosted page.

Format flexible : ASCII mockup dans le MD, HTML Pretext via skill design-html, ou Figma. L'important : S5 doit pouvoir coder sans relancer S4.

Gate Telegram (15 min)

🎨 ATELIER S4 — Approval scope nécessaire

Sprint : {sprint_id} · {nom validé S3}

Features v1 (et SEULEMENT ces 3) :
1. {Feature 1, 1 ligne}
2. {Feature 2}
3. {Feature 3}

Out of scope v1 :
- {7+ features explicitement retirées}

Design ref primaire : {Linear / Mercury / Cuely / Stripe / ...}
Palette : {3 emoji-color blocks}

Réponds : GO ou REVOIR

Prompt canonique (Opus 4.7 thinking)

Tu es S4 Product Designer d'Atelier. Tu reçois l'état startup.json après S3.

Tu produis :

1. RUTHLESS SCOPING — analyse 10 features potentielles déduites du one-pager S1.
   Pour chaque : indispensable oui/non, indépendante oui/non, < 1 jour de build oui/non.
   Garde 3 (et seulement 3) features pour v1. Justifie pourquoi pas les autres.

2. POUR CHAQUE FEATURE — user story (format "En tant que X, quand Y, je Z, pour W") + 3-5 acceptance criteria testables.

3. OUT OF SCOPE v1 — liste explicite de 7+ features retirées.

4. DESIGN TOKENS — JSON complet selon le schéma (palette, typography, motion, radius, spacing).
   Choisis 1 ref primaire parmi les options de taste.md et adapte.

5. 5 WIREFRAMES — ASCII mockups ou HTML Pretext. Login, onboarding, main view, settings, Stripe checkout.

Format final : Markdown structuré + JSON tokens séparé.

State input :
<input>
{startup_json_after_s3}
</input>

Reference taste :
<input>
{playbook/taste.md raw}
</input>

Anti-patterns

  • 4 features parce que "elles sont toutes critiques" → non. Si elles sont 4 critiques, le scope du produit n'est pas clair. Re-lire le one-pager S1, retirer.
  • Wireframes pixel-perfect → temps perdu. Wireframes lo-fi mais explicites suffisent. Le pixel-perfect arrive en S5 avec shadcn/ui.
  • "On verra le pricing en S6" → non. Le Stripe checkout wireframe doit montrer le pricing finalisé. Le pricing est une feature de S4, pas de S6.
  • "Out of scope list = 0 items" → impossible. Si tu n'as rien retiré, c'est que tu n'as pas vraiment scopé. Force-toi à en retirer 7.
  • Design tokens sans ref primaire → "on fera notre style" → AI slop garanti. Choisis 1 ref, copie sa logique, dévie au strict minimum.

Lien S5

Le 04-spec.md + 04-design-tokens.json + wireframes/ sont les 3 inputs canoniques de S5 Build. Le Builder agent (v1) ne devra rien d'autre pour coder.

Update startup.json (après S4)

{
  "current_station": "S5",
  "s4_spec": {
    "completed_at": "<iso8601>",
    "telegram_gate_approved_at": "<iso8601>",
    "doc": "04-spec.md",
    "features_v1": [
      { "name": "...", "user_story": "...", "acceptance_criteria": [...] },
      { ... },
      { ... }
    ],
    "out_of_scope_v1": [/* 7+ items */],
    "design_tokens": { /* JSON complet */ },
    "wireframes": ["wireframes/01-login.png", ...]
  }
}