Expériences visuelles
Règles pour enrichir Orbit sans casser le design system natif de Documentation.AI.
Principe : native first
Documentation.AI reste le design system principal.
Orbit ne recrée pas :
- le layout ;
- les cards ;
- les headings ;
- la navigation ;
- le système de thème ;
- les composants de base.
Le Custom CSS et les éventuels Custom Scripts servent uniquement de surcouche ciblée.
Ce que nous personnalisons
| Élément | Règle |
|---|---|
| Headers de tableaux | Noir pur pour créer un contraste clair dans les listes |
| Dark mode | Le moteur natif reste actif ; les grandes surfaces utilisent #000 plutôt qu’un gris foncé |
| Frames de features | Ponctuelles, uniquement pour une vraie démo ou un élément important |
| Mermaid | Architecture, séquences et relations |
| Board | Roadmap et états de delivery |
| Iframe / Video | Démonstrations réelles quand la ressource a le même niveau d’accès |
Ce que nous évitons
- gros hero custom dans une page de documentation ;
- cartes recréées autour des headings ;
- animations décoratives ;
- CSS qui redessine l’intégralité du template ;
- JavaScript qui force le thème du lecteur ;
- visualisation simplement « jolie » sans valeur explicative.
Motions
Une motion est acceptable seulement si elle représente une transition produit réelle :
- encodage ;
- compression ;
- passage d’un état à un autre ;
- progression d’un workflow.
Dans tous les autres cas, utiliser le composant natif le plus simple.
Frames
Une vraie feature interactive peut être intégrée avec <Iframe> ou <Video>.
Pour une ressource privée, la cible embarquée possède sa propre authentification serveur. L’ACL de la page Documentation.AI ne protège pas automatiquement une URL externe.
Thème sombre par défaut
Documentation.AI ne documente pas aujourd’hui de propriété defaultTheme dans documentation.json.
Orbit utilise donc un Custom Script minimal qui choisit le sombre uniquement lors de la première visite lorsqu’aucune préférence de thème existante n’est détectée.
Le lecteur reste libre de repasser en clair. Le script ne recrée aucun composant ni système de thème.
Le Custom CSS transforme ensuite les grandes surfaces du dark mode en #000000 pur.