Composants de console de design

Trois composants existent pour documenter un système de design. La console de design de Sovrium est construite avec eux, et votre application peut bâtir la sienne de la même façon.

Ils lisent votre design plutôt que de le répéter, et c'est tout l'intérêt. Une page qui écrit sa propre copie d'un bouton montre à quoi ce bouton ressemblait le jour où il a été tapé. Un specimen dessine celui que votre application rend maintenant.

Les jetons de design eux-mêmes sont dessinés par des types de kit ordinaires : swatch peint un jeton de couleur et trace un jeton d'accélération, badge avec variant: contrast note une paire pour sa lisibilité, et card avec variant: scoped marque une frontière de design sur une page qui montre deux systèmes à la fois.

specimen

Dessine un composant à côté du littéral de configuration qui l'a produit. Les deux sont projetés depuis la même déclaration : l'extrait ne peut donc pas cesser de correspondre à ce qui est au-dessus.

subject accepte type, component, variant, size et state. annotations emploie les mêmes noms de parties que le bloc components d'un design.

components:
  - type: specimen
    showSnippet: true
    showProvenance: true
    annotations:
      - { part: root, label: The button itself }
    component:
      type: button
      label: Save changes

Nommer un sujet plutôt que de l'écrire

component porte un littéral, et c'est ce qui rend l'extrait honnête — mais cela veut dire aussi qu'une déclaration dessine un type. Une route de kit par type exigerait une page par type. Un specimen peut donc plutôt nommer son sujet, et Sovrium dessine son propre specimen de catalogue pour ce type, avec les propriétés illustratives dont chaque type a besoin pour être le specimen de quelque chose. Rendu nu, un select est une boîte vide ; c'est dans le catalogue que vit cette connaissance.

pages:
  - path: /kit/:type
    components:
      - type: specimen
        subject: { type: $param.type }
        showSnippet: true

subject.type est soit un nom de type catalogué (button), soit $param.<nom> désignant un segment du chemin de la page hôte. Un littéral est vérifié à la lecture de la configuration : une faute de frappe, ou un type qu'un specimen ne peut jamais dessiner, est nommé au démarrage. Un $param est un segment d'URL plutôt qu'un fait de configuration : un segment ne désignant rien de dessinable répond donc 404 — une URL mal tapée qui afficherait silencieusement une page ferait passer un lien mort pour vivant, et un cadre vide laisserait croire à un lecteur que le type n'a pas de specimen plutôt que pas d'existence.

component et subject s'excluent mutuellement, et exactement l'un des deux est requis. Tous deux répondent à « qu'est-ce qui est dessiné », et il n'y a pas d'ordre de priorité défendable entre eux : un specimen déclarant les deux en montrerait un et jetterait l'autre en silence, avec l'extrait projeté depuis lui.

Un specimen refuse de dessiner un composant qui rend un contrôle de soumission — form — à quelque profondeur que ce soit, et refuse de s'imbriquer dans un autre specimen. Le premier refus est une règle de sûreté : un cadre d'aperçu ne porte aucun chemin d'écriture. Le second est une borne : chaque niveau projette son extrait depuis le niveau inférieur, et l'imbrication n'aurait donc pas de fin. Les deux sont refusés à la lecture de la configuration, pour que l'échec nomme sa raison au lieu de ne rien dessiner en silence.

field-specimen

Dessine le contrôle qu'obtient un type de champ de table : un type de colonne, rendu comme le contrôle de formulaire que votre formulaire d'enregistrement affichera réellement pour lui. Là où specimen documente la moitié « composants » d'un système de design, celui-ci en documente la moitié « données ».

fieldType accepte un nom de type de champ catalogué, $param.<nom> désignant un segment de chemin, ou $record.<champ> désignant une colonne de la ligne depuis laquelle le specimen est déployé.

components:
  - type: field-specimen
    fieldType: single-select
    label: Status
    options: [Draft, Sent, Paid]

Il documente une surface, et dit laquelle

Un type de champ est dessiné sur plus d'une surface, et ces surfaces diffèrent légitimement. Un specimen ne peut donc pas prétendre montrer le rendu d'un type de champ. Il montre le contrôle d'une surface nommée, et porte une légende disant laquelle. compact supprime cette légende pour une page qui dessine tous les types à la fois, où la même phrase a sa place une fois au-dessus du groupe plutôt que des dizaines de fois à l'intérieur.

Là où une surface n'a pas encore de contrôle exact, le specimen se signale comme différé plutôt que de dessiner une approximation et de vous laisser y croire. compact ne supprime jamais ce marqueur : masquer une légende est un choix de mise en page, masquer un avertissement de fidélité n'en est pas un.

Il héberge un contrôle, et n'offre aucun moyen de le soumettre

Le contrôle dessiné est un vrai contrôle : le même que celui qu'affiche votre formulaire d'enregistrement, pas un sosie construit à côté — c'est ce qui empêche la page de dériver loin du formulaire. Il est hébergé directement, sans form autour et sans affordance de soumission, pour que quiconque peut lire la page ne puisse pas devenir par accident l'éditeur de quoi que ce soit.

Il n'y a ni propriété surface ni fullWidth. La première vous demanderait d'épeler une constante — il y a une surface aujourd'hui, et la propriété apparaîtra le jour où il y en aura une seconde. La seconde est de la mise en page, et la mise en page appartient au conteneur dans lequel vous placez le specimen, pas à un fait concernant le type de champ.

preview

Dessine une option d'un type, réglée sur la valeur que vous nommez — pour qu'un réglage puisse être vu plutôt que décrit.

subject.type est un nom de type catalogué, ou $param.<nom>, ou $record.<champ>. subject.option est un chemin dans la grammaire pointée que publie le point d'entrée des options de type de composant, avec [] pour un niveau de tableau. subject.value est une chaîne, un nombre ou un booléen ; une chaîne est convertie selon la nature propre de l'option, si bien qu'un gabarit de ligne portant $record.value dessine la même chose qu'un littéral 2.

components:
  - type: preview
    subject: { type: table, option: pagination.position, value: both }
    caption: 'Pagers above and below, for a grid taller than the viewport.'
  - type: preview
    subject: { type: table, option: striped, value: true }
    showValue: false

Il dessine une valeur, pas une variante

specimen dessine un composant dans un état — une variante, une taille, une apparence au repos ou au survol —, et ses champs d'axe sont réellement optionnels, parce qu'un type a une variante par défaut et une taille par défaut. Un aperçu dessine une option à une valeur, et aucune option n'a d'« option par défaut » : voilà pourquoi les trois parties de subject sont requises plutôt qu'optionnelles.

Une valeur structurée est délibérément exclue. Une option dont la valeur est un objet n'est pas de celles qu'un lecteur apprend d'une seule image, et en admettre une rendrait la légende impossible à écrire. La chaîne vide, à l'inverse, est délibérément admise : la valeur intéressante d'une vraie option est parfois '' — un placeholder vide, un emptyText vide —, et une image de cela est exactement ce dont un lecteur a besoin.

La légende est écrite, pas générée

La description d'un schéma dit ce qu'une option est. Ce dont un lecteur a besoin à côté de l'image, c'est de ce que cette valeur lui fait, et c'est une phrase que seul un auteur peut écrire. Omettez caption là où l'effet est évident ; la console de Sovrium en écrit une par ligne, ce qui donne une idée honnête de la fréquence à laquelle il ne l'est pas.

showValue est actif par défaut, et la console le désactive parce que chacune de ses lignes de configuration imprime déjà le chemin de l'option dans sa colonne de gauche. Une application qui dessine un aperçu isolé sur sa propre page le laisse actif.

Pages connexes

• Système de design — le bloc design que ces trois composants lisent.
• Composants spécialisés — les autres types de la même section.
• Présentation des types de champs — les types dont field-specimen dessine les contrôles.