croct-tech/agent-skills

Modéliser le contenu Croct

Concevez des composants et des emplacements, rédigez leurs schémas et remplissez-les de définitions de contenu qui restent valides à mesure que le modèle évolue. Tout ce qu'un schéma peut exprimer existe également dans l'éditeur visuel du tableau de bord ; le JSON est le même modèle, écrit à la main.

Modèle mental

Concept	Ce que c'est	Portée
Composant	Un schéma nommé et réutilisable. Seules les structure et union peuvent être des composants (schémas de premier niveau).	Réutilisable entre les emplacements et les autres composants
Composant régulier	Une structure avec un ensemble fixe d'attributs.
Composant union	Une union d'au plus 10 composants réguliers ; l'éditeur choisit une variante par contenu.
Emplacement	Un espace réservé dans l'application (hero, barre d'annonce) lié à un composant. Contient le contenu par défaut par langue.	Spécifique au contexte ; un composant peut alimenter plusieurs emplacements
Définition de contenu	JSON contenant les valeurs réelles d'un schéma, avec des valeurs statiques ou dynamiques (CQL).

Les couches de contenu, de la base au sommet : contenu par défaut de l'emplacement (affiché lorsqu'aucune expérience ou expérimentation ne correspond, pour les bots exclus par le filtrage des bots, lors du rendu statique et en cas d'erreur) -> contenu d'expérience (par audience) -> contenu d'expérimentation (par variante, au moins deux variantes) -> groupes de contenu (variations supplémentaires pour les sous-segments d'une expérience ou d'une variante d'expérimentation). Le contenu de secours se trouve dans le code source de l'application et s'affiche en cas d'échec de la récupération ou de suspension du service ; l'interface en ligne de commande télécharge le contenu par défaut de l'emplacement comme contenu de secours.

Décider de la forme

Si vous avez besoin de...	Utilisez
Une mise en page fixe (mêmes champs partout)	Composant régulier (structure)
Des variations que l'éditeur choisit (bannière texte vs bannière image vs bannière formulaire)	Composant union référençant des composants réguliers
Une cohérence entre plusieurs endroits (un bouton CTA utilisé partout)	Un composant séparé, intégré avec {"type": "reference", "id": "..."}
De la flexibilité à un endroit (une paire titre + image)	Un attribut structure imbriqué ou des primitives, pas un nouveau composant
Une page avec plusieurs sections indépendantes	Un composant et un emplacement par section, pas un composant géant
Un ensemble prédéfini d'options	text avec choices (Énumération)
Image, vidéo, audio ou téléchargement de document	reference sur @croct/file (les fichiers sont limités à 5 Mo ; pour les vidéos plus longues, envisagez un attribut texte url à la place)
Texte formaté édité dans un éditeur à barre d'outils	reference sur @croct/richText
Mise en forme légère dans un champ texte brut	text + un analyseur Markdown dans l'application (voir Markdown ci-dessous)
Une valeur utilisée uniquement pour calculer d'autres valeurs (par exemple, une variable dynamique)	Attribut avec "private": true

Règle empirique issue de la documentation : demandez-vous « Ai-je besoin de flexibilité ou de cohérence ? » Flexibilité -> attribut de structure. Cohérence -> nouveau composant.

Flux de travail

1. Listez les sections de la page ; chaque section placée indépendamment devient un emplacement.
2. Pour chaque emplacement, choisissez un composant régulier ou union. Réutilisez les composants existants lorsque la structure est censée rester cohérente.
3. Rédigez le schéma : attributs avec type, label, description, position et optional là où le contenu peut être absent. Ajoutez la validation (maximumLength, minimum, pattern, allowedTypes, maximumLength sur les listes) à partir des contraintes réelles de l'interface utilisateur.
4. Vérifiez les limites (ci-dessous) avant d'ajouter de l'imbrication. Calculez le score de complexité.
5. Rédigez la définition de contenu par défaut pour chaque emplacement et chaque langue prise en charge.
6. Si le composant est déjà utilisé, attendez-vous à une nouvelle version en cas de modifications cassantes ; mettez à jour la version de l'emplacement dans l'application après avoir mis à jour le contenu affecté (voir Versioning).

Squelette de schéma

Un composant régulier est une structure. Chaque attribut encapsule son schéma dans type :

{
  "type": "structure",
  "title": "CTA Button",
  "description": "A call-to-action button that links to a page.",
  "attributes": {
    "label": {
      "label": "Label",
      "description": "The text displayed on the button.",
      "position": 0,
      "type": {
        "type": "text"
      }
    },
    "link": {
      "label": "Link",
      "description": "The URL of the page to link to.",
      "position": 1,
      "type": {
        "type": "text"
      }
    }
  }
}

Un composant union fait correspondre les identifiants de composant à des références. Les clés doivent être égales aux identifiants référencés :

{
  "type": "union",
  "types": {
    "text-hero": {"type": "reference", "id": "text-hero"},
    "image-hero": {"type": "reference", "id": "image-hero"}
  }
}

Dans l'application, le contenu d'un emplacement union est une union discriminée : chaque variante a une propriété _type définie sur l'identifiant du composant (text-hero ou image-hero ci-dessus). Branchez-vous sur _type pour l'afficher ; consultez la compétence croct-integrate-sdk.

Types d'attributs en un coup d'œil

Type du tableau de bord	Schéma JSON
Texte	{"type": "text"} (+ minimumLength, maximumLength, pattern)
Texte multiligne	{"type": "text", "format": "multiline"}
URL	{"type": "text", "format": "url"}
Couleur	{"type": "text", "format": "color"}
Date / heure	{"type": "text", "format": "instant"} (aussi local-date, local-time, local-date-time, zoned-date-time)
Énumération	{"type": "text", "choices": {"left": {"label": "Left"}}}
Texte enrichi	{"type": "reference", "id": "@croct/richText", "properties": {}}
Fichier	{"type": "reference", "id": "@croct/file", "properties": {}}
Nombre	{"type": "number"} (+ integer, minimum, maximum)
Booléen	{"type": "boolean"} (+ label.true, label.false, default)
Liste	{"type": "list", "items": {...}} (+ itemLabel, minimumLength, maximumLength)
Structure	{"type": "structure", "attributes": {...}}
Composant	{"type": "reference", "id": "<component-id>"}

format et choices ne peuvent pas être combinés avec une autre propriété de texte, sauf type. Listes complètes des propriétés, valeurs par défaut et limites : references/schema.md.

Limites du schéma

Limite	Valeur
Attributs par structure	30
Profondeur d'imbrication	6 niveaux
Composants dans une union	10
Score de complexité du schéma	50
Éléments de liste (maximumLength par défaut du schéma)	30
maximumLength du texte	300 pour une ligne ; 1000 pour multiligne et URL (limite implicite : le text brut ne peut pas combiner format avec maximumLength ; le texte enrichi le peut)
choices de texte	20
Taille du fichier	5 Mo (5242880 octets)
Libellés / descriptions	60 / 160 caractères

Score de complexité : structure = 1 + ses attributs ; liste = 1 + son type d'élément ; primitive = 1 ; union = son membre le plus complexe ; référence = le composant référencé. Une liste de produits avec titre, image et prix obtient un score de 5.

Squelette de définition de contenu

Chaque valeur est {"type": "<content type>", "value": {"type": "static" | "dynamic", ...}}. Les structures imbriquent attributes ; les listes contiennent items ; le contenu union est une structure avec name défini sur la clé de l'union.

{
  "type": "structure",
  "attributes": {
    "message": {
      "type": "text",
      "value": {"type": "static", "value": "Welcome, {{variable}}!"}
    },
    "variable": {
      "type": "text",
      "value": {
        "type": "dynamic",
        "expression": "user's name",
        "nullable": true,
        "default": "guest"
      }
    }
  }
}

• expression est du CQL (voir la compétence croct-cql). default est utilisé lorsque l'évaluation échoue, retourne null ou retourne un type incompatible.
• nullable doit correspondre à l'indicateur optional de l'attribut dans le schéma.
• Marquez les attributs auxiliaires comme variable avec "private": true dans le schéma afin qu'ils restent en dehors du contenu livré à l'application.
• Limites du contenu : jusqu'à 30 éléments de liste, jusqu'à 10 valeurs dynamiques, score de complexité 50.
• Les valeurs dynamiques sont une fonctionnalité du plan Scale ; la localisation est un module complémentaire.

Espaces réservés, chemins relatifs, valeurs de secours et chaque type de contenu : references/definition.md.

Localisation

• Les langues sont configurées par espace de travail. La localisation est un module complémentaire.
• Fournissez un contenu par défaut pour chaque emplacement et chaque langue prise en charge. Une langue sans contenu par défaut utilise le contenu de la langue par défaut. Les expériences et expérimentations contiennent également du contenu par langue ; une expérience sans contenu pour une langue sert le contenu par défaut de l'emplacement.
• Valeur de secours lorsque la langue demandée est manquante : la documentation SDK indique la langue par défaut de l'espace de travail ; la documentation de l'API Content indique la langue par défaut de l'emplacement. Les docs sont en désaccord ; dites-le plutôt que d'en choisir une.
• Demandez une langue dans le code avec preferredLocale (par récupération) ou defaultPreferredLocale (à l'échelle de l'application), ou localeResolver dans Next.js/Hydrogen ; consultez la compétence croct-integrate-sdk.
• croct.json contient defaultLocale et locales ; croct install télécharge le contenu de secours par emplacement, version et langue. Consultez la compétence croct-use-cli.

Versioning et modifications cassantes

1. Modifiez le schéma du composant, par exemple ajoutez un attribut ou modifiez-en un existant (l'exemple de la documentation).
2. Lorsque la modification affecte la structure du contenu d'une manière qui pourrait casser l'application, Croct crée une nouvelle version et continue de servir l'ancienne à l'application.
3. Mettez à jour le contenu de chaque emplacement et expérience affectés (le tableau de bord les signale).
4. Mettez à jour la version de l'emplacement dans le code de l'application, par exemple fetchContent('home-hero@2').

À faire :

• Épinglez les versions des emplacements (home-hero@1) dans le code de l'application. Les identifiants non versionnés utilisent la dernière version, donc les modifications cassantes prennent effet immédiatement et peuvent casser l'application.
• Mettez également à jour le contenu des expériences et expérimentations, pas seulement le contenu par défaut de l'emplacement.
• Maintenez le contenu de secours synchronisé après les modifications (la compétence croct-use-cli couvre la synchronisation).

À ne pas faire :

• Ne présumez pas des modifications qui sont cassantes. La documentation ne les liste pas ; fiez-vous à l'alerte d'impact sur l'emplacement du tableau de bord.

Refactoring

Situation	Technique
Une modification doit s'appliquer à la plupart, mais pas à toutes les utilisations	Dupliquer et modifier : dupliquer le composant, pointer les quelques exceptions vers la copie, puis modifier l'original
Une modification doit s'appliquer à seulement quelques utilisations	Dupliquer et remplacer : dupliquer, modifier la copie, pointer ces utilisations vers la copie
Le composant a atteint le niveau d'imbrication maximal	Aplatir et fusionner : fusionner les attributs d'une structure imbriquée dans le parent, puis mettre à jour le contenu partout où il est utilisé
Le composant est proche de la limite de complexité	Diviser en composants plus petits rendus par des emplacements séparés
La structure a atteint la limite de 30 attributs	Conseil (la documentation n'a pas de guide pour cela) : regrouper les attributs connexes dans des structures imbriquées, en restant dans les 6 niveaux d'imbrication, ou diviser en composants et emplacements séparés. Les versions épinglées des emplacements (home-hero@1) maintiennent l'application en direct sur l'ancien schéma pendant la migration

Détails, étapes et bonnes pratiques : references/design-and-refactoring.md.

Markdown dans les attributs texte

• Le texte enrichi (@croct/richText) stocke le Markdown produit par un éditeur à barre d'outils ; restreignez-le avec allowedFormatting.
• Les attributs text bruts stockent des chaînes brutes. Pour prendre en charge Markdown ici, analysez-le dans l'application, par exemple avec @croct/md-lite (gras, italique, barré, code, lien, image, paragraphe).
• Limitez-vous à une mise en forme simple. Modélisez les libellés CTA, les URL et les données produit comme des attributs séparés.
• Indiquez la syntaxe prise en charge dans la description de l'attribut, par exemple "Prend en charge la syntaxe markdown pour **gras**, *italique* et [liens](https://example.com\)."

Code de rendu : references/design-and-refactoring.md.

Pièges

• Créer des composants pour des titres ou des images uniques. Utilisez des primitives ou des structures.
• Noms génériques ("Product cards"). Privilégiez les noms d'usage ("Product feature list").
• Les clés types de l'union qui diffèrent des identifiants des composants référencés : le schéma est invalide.
• Plus d'une entrée choices avec "default": true : le schéma est invalide.
• Valeurs date/heure sans secondes : 10:15 est invalide, 10:15:00 est valide.
• Valeurs dynamiques avec nullable qui ne correspond pas à l'indicateur optional du schéma.
• Les aperçus affichent un contenu obsolète lorsque la version de l'emplacement de l'expérience diffère de la version de l'application.

Documentation en direct

• Index : https://docs.croct.com/llms.txt
• N'importe quelle page en markdown : https://docs.croct.com/reference/content/schema/introduction.md
• Recherche : https://docs.croct.com/api/search.md?term=<terms>