Callout
Un aviso que forma parte del contenido y se queda en él (una nota, una precaución, el motivo de algo o un resumen de lo que está mal), con un relleno discreto o con contorno, en los colores de un estado y con su glifo, con un título, acciones y un botón de cierre opcionales.
- Categoría
- Comunicación
- Tokens
comp.callout- Nivel
- Base
- Web
tanrei-calloutschedule - SwiftUI
TanreiCalloutradio_button_unchecked - Jetpack Compose
TanreiCalloutradio_button_unchecked - Flutter
TanreiCalloutradio_button_unchecked - React Native
Calloutradio_button_unchecked
Generado a partir de docs/status/status.json, specs/callout.spec.json
Una nota, una precaución con título y un aviso con acciones y botón de cierre
Un callout es un aviso en el flujo de la página: se queda donde lo pones, con la anchura de su lugar, durante tanto tiempo como el contenido. De forma predeterminada es una nota, que se lee donde está igual que el párrafo anterior, y nunca recibe el foco.
En la web es <tanrei-callout>. Las demás plataformas todavía no lo han implementado.
El cuerpo es el propio contenido del elemento. El título es el atributo headline, o el slot title cuando es contenido tuyo o un encabezado. Un glifo del conjunto de iconos va en el slot icon, y tus propios botones o enlaces, en el slot actions.
<!-- Una nota. Su estado está en las palabras del título. -->
<tanrei-callout status="info">
<p slot="title">Nota</p>
Los estilos de texto se nombran por nivel, nunca por tamaño.
</tanrei-callout>
<!-- El título no dice el estado: status-label se lee primero («Advertencia, …») y no se dibuja. -->
<tanrei-callout status="warning" status-label="Advertencia" headline="Accesibilidad">
A un preajuste se le exige fidelidad a su original, no estos umbrales de contraste.
</tanrei-callout>
<!-- Un consejo: sin estado, con tu glifo y con la palabra en el título. -->
<tanrei-callout headline="Consejo">
<span slot="icon">lightbulb</span>
Mantén habilitada una acción y explica qué falta cuando se use.
</tanrei-callout>
<!-- El contenido extenso es prosa, con el tamaño del callout y sin medida. -->
<tanrei-callout size="large" status="warning">
<h3 slot="title">Haz una copia de seguridad antes de migrar</h3>
<div class="tanrei-prose" data-size="large" data-measure="false">
<p>La migración reescribe la base de datos en su sitio. <a href="#restore">Consulta cómo restaurar una copia</a>.</p>
<ul><li>…</li></ul>
</div>
</tanrei-callout>
<script type="module">
import '@tanrei/web/components/callout';
import '@tanrei/web/callout.css'; // la caja que conserva un callout renderizado en el servidor antes de que se defina el elemento
</script>import { Button, Callout } from '@tanrei/react';
<Callout status="warning" headline="El archivo ha cambiado en el disco" live open={conflict} closable closeLabel="Cerrar" onDismiss={() => setConflict(false)}>
Aquí tienes cambios que no están en él. No se sobrescribe nada hasta que elijas.
<Button slot="actions" variant="outlined" onClick={reload}>Volver a cargar desde el disco</Button>
<Button slot="actions" variant="text" onClick={keep}>Conservar los míos</Button>
</Callout>Los dos aspectos en cada estado
Un título, tu propio glifo, acciones, un botón de cierre y el tamaño grande
Anatomía
Anatomía
tonal, tal como lo dibuja el paquete web.| Parte | Descripción |
|---|---|
1 container | The block that holds the notice, as wide as its place in the layout and as tall as its content, flat on the surface it sits on. Filled in the tonal look (a quiet neutral, or a status's quiet container) and edged in the outlined look. It carries no state: nothing about it answers a pointer, a press or focus. |
2 outline · opcional | The outlined look's edge: one hairline inside the container, the same in every status. |
3 icon · opcional | The glyph at the start, on the first line of the text: the status's glyph from the system's icon set (info, warning, error or check_circle, the ones a snackbar draws), or the glyph the product names. In the status's own color, a little softer than the text. Decorative: the status is given in words. |
4 title · opcional | A few words that name the notice, above the body. Plain text unless the product gives a heading; it wraps and is never cut. |
5 body | The notice itself: the product's content, from one sentence to several paragraphs with lists, links, code and tables. Long-form blocks in it are prose. |
6 actions · opcional | One or two of the product's own Buttons or links that follow up on the notice, in a row below the text. |
7 close-button · opcional | An icon-only Button of the small size showing the close glyph at the end of the first row, in the variant comp.callout.close-button.variant names (tonal in the default system) and, on a filled look, in the tone of that fill: its content color, so that its container is that color made translucent and its glyph is that color. The callout places it and chooses its variant and its tone; everything else it reads from Button's own tokens. The only part of a callout that answers a pointer, a press or focus, and it answers as a Button. |
Medidas
Medidas
| Longitud | Token | Valor (px) |
|---|---|---|
container padding-inline | tanrei.comp.callout.container.padding-inline | 16 |
tonal, tal como lo dibuja el paquete web.Propiedades
| Propiedad | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
title | string | "" | A few words above the body that name the notice ("Not published yet"). Plain text, never a heading. Empty draws the body alone. The title slot takes its place where the product needs a heading of its own level or inline content. |
status | default | info | warning | error | success | "default" | What the notice is, in the names the snackbar and the tag use. default: a neutral aside, with no glyph unless the product gives one. info, warning, error and success draw the look in that status's color roles with that status's glyph; a live callout is announced assertively for warning and error. Use them for what they mean everywhere in the system: advice is not a success. |
statusLabel | string | "" | The status in words, in the product's language ("Warning"), read by assistive technology before the title and the body and not drawn, so that the status never rests on color and glyph alone. For a callout whose title does not itself say the status; needed when it has a status and no title. Ignored while status is default. |
variant | tonal | outlined | "tonal" | How much the callout weighs. tonal: a quiet fill, the default. outlined: no fill and one hairline, for a callout on a tinted surface or inside a filled card, where a fill would vanish, and for many callouts close together. A design system may add values. |
size | medium | large | "medium" | The size of the text, in prose's two sizes. medium sets the body in the interface's own text style, for a callout among controls: a form, a panel, a dialog. large sets it in the style for long reading, for a callout in a page whose purpose is the text. Paddings, the glyph and the close button are the same at both. A design system may add values. |
live | boolean | false | Whether the callout is announced. False, the default, is for a callout that is part of what was written: it is a note, read where it stands. True is for one that appears or changes in answer to something (a summary of a form's errors after a submit, a notice that the file changed underneath the person): it is a live region, announced once when it is shown and when its content changes, politely or, for warning and error, assertively. It changes nothing that is drawn. |
closable | boolean | false | Draws a close button, for a notice the person may put away (an announcement, a hint they have read). A caution that qualifies the content beside it should not be closable. |
closeLabel | string | "" | The close button's accessible name, in the product's language ("Close"). Required while closable is true. |
open | boolean | true | Whether the callout is shown. The close button sets it to false; the product sets it to show a callout again or to show one in answer to something. A callout that is not open draws nothing and takes no space. |
Slots
| Slot | Descripción |
|---|---|
default | The body: text, or the product's own blocks (paragraphs, lists, a table, a code block, any component). Long-form blocks are laid out as prose of the callout's size. |
icon | A glyph of the system's icon set, by name, drawn in place of the status glyph, or as the glyph of a callout without a status (a tip's lightbulb). |
title | The product's own title content in place of the title prop: text with inline content, or a heading of the level the page's outline needs. The callout draws it in the title's style and changes neither its role nor its level. |
actions | The actions: the product's own Buttons or links, one or two. The callout lays them out below the text and does nothing else to them. |
Eventos
| Evento | Descripción |
|---|---|
dismiss | The person closed the callout with its close button. Emitted exactly once, after open became false; never emitted when the product sets open. |
Estados
Comportamiento
Requisitos en formato EARS. Cada implementación de plataforma se prueba contra estos identificadores. El texto de los requisitos se muestra tal como está en la especificación, en inglés.
| ID | Requisito |
|---|---|
CLO-1 | THE callout SHALL draw a container as wide as the layout it is placed in gives it (CLO-22) and as tall as its content, with corners comp.callout.container.shape eased by sys.shape.corner-smoothing and no elevation, padded by comp.callout.container.padding-block above its first line and below its last block, by comp.callout.container.padding-inline at the start, and at the end by comp.callout.container.padding-inline where the text meets it or by comp.callout.container.padding-inline-end-with-close after the close button. Inside it SHALL lay out, from the start: the glyph, where it has one (CLO-5, CLO-6); comp.callout.icon.gap after it a column that takes the remaining width and holds the title (CLO-7), the body (CLO-8) and the actions (CLO-9), in that order; and comp.callout.container.gap after that column the close button, where it has one (CLO-10). THE callout SHALL centre the glyph and the close button on the first line of the text (the title's, or the body's without a title) and keep them there however tall the text grows, and any height the container has beyond its content SHALL lie below the content. |
CLO-2 | WHILE status is default THE callout SHALL fill its container with the container color of its variant and draw its title, its body and a glyph the product gave in that variant's title, body and icon colors: comp.callout.container.color.tonal, comp.callout.title.color.tonal, comp.callout.body.color.tonal and comp.callout.icon.color.tonal for tonal, and outlined's tokens of the same names (comp.callout.container.color.outlined, comp.callout.body.color.outlined, and so on). |
CLO-3 | WHILE status is info, warning, error or success THE callout SHALL draw its container, its title, its body and its glyph from the parts of its variant prefixed with the status: for a tonal info callout comp.callout.info.container.color.tonal, comp.callout.info.title.color.tonal, comp.callout.info.body.color.tonal and comp.callout.info.icon.color.tonal; for outlined, and for warning, error and success, their own tokens of the same names (comp.callout.error.icon.color.outlined, comp.callout.success.container.color.tonal, and so on). A status SHALL change these colors, the glyph (CLO-5), the tone of the close button (CLO-10) and how a live callout is announced (CLO-21), and nothing else: the callout's size, shape, layout and edge stay those of its variant and size. |
CLO-4 | WHILE variant is outlined THE callout SHALL draw an edge comp.callout.outline.width wide in comp.callout.outline.color inside its container's size, following its corners, in every status, without changing the callout's size or the place of its content; WHILE variant is tonal it SHALL draw no edge. A status SHALL NOT color the edge: it is the system's one hairline. |
CLO-5 | WHILE status is info, warning, error or success and the icon slot is empty THE callout SHALL draw that status's glyph from the system's icon set (info for info, warning for warning, error for error, check_circle for success), the glyphs a snackbar draws, in a box of comp.callout.icon.size, in its form's icon color (CLO-3) drawn at comp.callout.icon.opacity (an opacity of the glyph alone, which fades nothing else), with sys.icon.family.unselected and sys.icon.fill.unselected, sys.icon.weight and an optical size clamped between sys.icon.optical-size.min and sys.icon.optical-size.max. The glyph so drawn SHALL keep 3:1 against its container in every scheme of the default system, and against every surface role in the outlined look. THE callout SHALL keep the glyph from assistive technology, which is given the status in words (CLO-20). WHILE status is default and the icon slot is empty THE callout SHALL draw no glyph and no room for one: the text starts at the start padding. |
CLO-6 | WHERE the icon slot holds a glyph THE callout SHALL draw it in the place, the box, the color and the opacity CLO-5 gives the status glyph (the icon color of its form, CLO-2 and CLO-3), in every status and without one, SHALL draw no status glyph beside it, and SHALL keep it from assistive technology: the product's glyph says what kind of notice this is (advice, an experiment, something new), and the words say it to everyone. |
CLO-7 | WHILE title is not empty THE callout SHALL draw it above the body in the text style of its size (comp.callout.title.typescale.medium for medium, comp.callout.title.typescale.large for large) and the title color of its form (CLO-2, CLO-3), with comp.callout.title.gap between it and the body; the title SHALL wrap and SHALL never be cut. WHERE the title slot holds content THE callout SHALL draw that content in the title's place, style and color instead of the title prop, and SHALL change neither its role nor its level: a title given as text is plain text and never a heading, and a title the product gives as a heading stays a heading of the level the product gave it, drawn as every other title is. WHILE both are empty THE callout SHALL draw the body alone, on the first line. THE callout SHALL set the title's letter-spacing by the script of its text, as every title is set (PRS-20): no negative letter-spacing WHERE its language is Chinese, Japanese or Korean, and none WHERE its script joins its letters or stacks marks on them. |
CLO-8 | THE callout SHALL draw the content of its default slot as its body, below the title, and SHALL give it the text style of its size (comp.callout.body.typescale.medium for medium, comp.callout.body.typescale.large for large) and the body color of its form (CLO-2, CLO-3) as the style and color its text takes where nothing inside sets another. The body SHALL wrap and SHALL never be cut or limited to a number of lines. WHERE the body holds long-form blocks (paragraphs, lists, a quote, a table, a code block) they SHALL be laid out as prose of the callout's size (PRS-1, PRS-5), without a measure of their own, so that the first block has no space before it and the last none after it and the body is exactly as tall as its content; the callout SHALL add no style to anything inside a component placed in its body, and a link in the body SHALL be underlined at rest (PRS-17). |
CLO-9 | WHERE the actions slot holds content THE callout SHALL lay it out as a row below the text (the body, or the title where there is no body), comp.callout.actions.gap below it, starting at the text's start edge, with comp.callout.actions.item-gap between two actions along the row and between rows where they wrap; an action's label SHALL NOT be cut to make the row fit. The actions are the product's own Buttons and links: THE callout SHALL NOT restyle them, SHALL NOT answer their presses and SHALL NOT close when one is activated. They SHALL follow the body in reading order and in the focus order, before the close button. |
CLO-10 | WHILE closable is true THE callout SHALL draw at the end of its first row an icon-only Button of the small size showing the glyph close of the system's icon set and named by closeLabel, in the variant comp.callout.close-button.variant names and, in every look but outlined, in the tone of its form (BTN-45): the body color of that form (comp.callout.body.color.tonal without a status, comp.callout.info.body.color.tonal for info, and so on), the content color of the fill it stands on, so that its container is that color made translucent and its glyph is that color; both given through the channel a Button reads from the component that places it, and otherwise unrestyled: it reads Button's own tokens, answers hover, focus and press as any Button does and keeps its own minimum target (BTN-5). The outlined look has no fill, so its close button takes no tone and is drawn as the variant draws it on the surface the callout sits on. THE callout's container, its text and its glyph SHALL NOT change under a pointer, a press or focus: the callout itself has no states. WHILE closable is false THE callout SHALL draw no close button and keep no room for one. |
CLO-11 | WHEN the user activates the close button by pointer, touch, Enter or Space THE callout SHALL set open to false, emit dismiss exactly once and close (CLO-13). THE callout SHALL NOT close by itself after a time, and SHALL NOT answer Escape: it is part of the content, and Escape belongs to whatever overlay or field the person is in. |
CLO-12 | WHEN a callout closes while focus is inside it THE callout SHALL move focus to the element that had it before focus entered the callout or, where that element no longer exists or cannot take focus, leave focus to the platform's default, so that the next Tab reaches what followed the callout; WHEN it closes while focus is elsewhere it SHALL NOT move focus. |
CLO-13 | WHILE open is false THE callout SHALL draw nothing, take no space and expose nothing to assistive technology, and its content SHALL NOT be reachable by focus; WHEN open changes THE callout SHALL appear or disappear at once, without a motion of its own, and SHALL emit dismiss only for a close the person made (CLO-11), never when the product sets open. |
CLO-19 | THE callout SHALL ease its container corners by sys.shape.corner-smoothing (0 is a quarter circle, 0.6 the iOS continuous corner; a platform with only the OS curve draws it for any amount above 0); a platform that cannot draw it SHALL fall back to a quarter circle and state that in its README. Its close button's corners and its focus indicator are the Button's (BTN-10). |
CLO-20 | WHILE live is false THE callout SHALL be exposed to assistive technology as a note: a part of the content that qualifies what is around it, read where it stands in reading order, named by its title where it has one and otherwise by statusLabel where status is not default and the product gave one. WHILE status is not default and statusLabel is not empty THE callout SHALL expose statusLabel as text before the title and the body, set apart so that it is read as a phrase of its own ("Warning, …"), and SHALL NOT draw it; WHILE status is default it SHALL ignore statusLabel. A callout that is not live SHALL NOT be announced when it is shown or when its content changes, SHALL NOT move focus, and SHALL NOT be a stop in the focus order: static content is not an alert. |
CLO-21 | WHILE live is true THE callout SHALL be a live region in place of a note. WHEN it is shown after its page or view was first presented (open becomes true, or the product adds it), and WHEN its title, its body or its status changes while it is shown, THE callout SHALL have assistive technology announce it once: statusLabel first when status is not default, then the title when it has one, then the whole body. It SHALL announce politely (after what is being read) when status is default, info or success, and assertively (interrupting what is being read) when status is warning or error, as a snackbar does, and SHALL NOT move keyboard or screen-reader focus. A live callout that is drawn with the first presentation of its page or view SHALL NOT announce itself then. live SHALL change nothing that is drawn. |
CLO-22 | THE callout SHALL lay itself out as a block in the flow of its container: it SHALL take the whole inline size the container gives it, in a page, in a list item, in a tab's panel, in a card or in another callout's body alike, with its start edge on the start edge of the text around it; it SHALL bring no outer space of its own (PRS-15: the space between it and its neighbours is its container's), SHALL never be wider than its container, SHALL have no minimum width, no maximum width and no measure of its own, and SHALL NOT scroll: content that cannot shrink (a table, a line of code) scrolls inside its own box. THE callout SHALL NOT float over the content, stick to an edge while the content scrolls or raise itself above it: where it stands is the product's layout. |
CLO-23 | WHILE the text size is enlarged THE callout SHALL grow its title and its body with it, keep its paddings and gaps, wrap, and grow in height; it SHALL keep the glyph's box at comp.callout.icon.size and the close button at its own size (a Button's icon-only circle, BTN-12), both still centred on the first line (CLO-1), SHALL cut nothing and set no fixed height, SHALL lose no content when the reader raises line height, paragraph spacing, letter spacing or word spacing, and SHALL need no horizontal scrolling at a width of 320 points with text at 200 %. |
CLO-24 | WHERE the platform draws with a person's own forced colors (the web's forced-colors mode, and a platform's equivalent where it has one) THE callout SHALL draw an edge comp.callout.outline.width wide in the platform's text color inside its container in every variant and status, its title, body and glyph in that text color with the glyph whole (no opacity), links in the platform's link color and still underlined, and its close button as a Button draws itself there, so that a look whose fill the mode removes is still a bounded block; the status SHALL then rest on the glyph's shape, the title's words and statusLabel. |
CLO-25 | WHERE the layout direction is right-to-left THE callout SHALL mirror the order of its content and apply its paddings by logical start and end: the glyph at the right, the text after it, the actions starting at the text's right edge and the close button at the left. |
CLO-26 | THE callout SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the callout is shown THE callout SHALL draw itself for the new direction at once, without a motion of its own, keeping its open state and its focus. |
CLO-27 | WHERE the layout direction is right-to-left THE callout SHALL draw the glyph of its icon slot mirrored left to right exactly when the system's icon set marks that glyph's name as mirrored or the product forces mirroring for that use, and unmirrored when the product forbids it: the icon helper mirrors the glyph inside its own box, about the box's vertical centre line, changing neither its place, size, color and opacity nor the order CLO-25 gives. THE callout SHALL NOT mirror a glyph itself, SHALL NOT mirror content the product gives as an image or a view of its own rather than by a glyph's name, and its own glyphs (the four status glyphs) are drawn through the same helper, which mirrors none of them under the default icon set; the close button's glyph is the Button's (BTN-19). |
CLO-28 | THE callout SHALL lay out a title given as text as text of its own direction, isolated from the text around it: it takes the base direction of its first strong character, or the layout direction where it has none, so that a left-to-right name, a number with its unit and a version keep their own order in a right-to-left layout and reorder nothing beside them; THE callout SHALL still place the title and align its lines by the layout direction, not by the text's own. The body's blocks are laid out as prose lays out a block (PRS-25): each by its own first strong character unless the content states a direction, with its lines aligned to the start edge of the layout. |
CLO-29 | WHILE the system's icon set cannot yet draw a glyph the callout draws itself (a status's glyph, or the icon slot's; its font is still loading) THE callout SHALL draw nothing in that glyph's place, never the glyph's name as text, SHALL keep the glyph's box, and SHALL draw the glyph once the set can; statusLabel and closeLabel SHALL still reach assistive technology. The close button's glyph is the Button's to draw. |
CLO-30 | WHEN variant or size names a value that the active design system does not have, or status names a value this spec does not have, THE callout SHALL render with the default value (the default variant's or size's tokens, status default), and in debug builds report the unknown value. |
CLO-31 | IF the title, the title slot and the body are all empty THE callout SHALL draw nothing, take no space and expose nothing, and in debug builds report that a callout has no content: a glyph, actions or a close button alone are not a notice. WHILE status is not default and both the title and statusLabel are empty THE callout SHALL still render and in debug builds report that the status is not given in words; WHILE closable is true and closeLabel is empty it SHALL still render the close button and in debug builds report that the button has no accessible name; IF statusLabel is not empty while status is default THE callout SHALL ignore it and in debug builds report it. |
CLO-32 | WHERE the platform has ARIA attributes (the web), the host carries its note or live region role (CLO-20, CLO-21) itself, so what the product writes on it is not moved, but for a name: WHILE its name (its title, else statusLabel) is not empty THE callout SHALL hold the product's aria-label and aria-labelledby on that host as their data-aria- twins, so that its name (its title, else statusLabel) is its whole name although the platform gives aria-labelledby the precedence, and WHEN its name (its title, else statusLabel) is emptied SHALL give them back as they were written; WHILE its name (its title, else statusLabel) is empty a name the product gives so — aria-label, or aria-labelledby naming an element — SHALL be its name. WHILE it is closed or empty (CLO-13) it exposes nothing, and SHALL hold them as well, giving them back when it is shown. WHEN the product removes one, or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaLabelledByElements) to null, THE callout SHALL take it away. |
Correspondencia de nombres por plataforma
Paridad no significa API idénticas. Cada plataforma expresa el mismo contrato con su propio estilo.
| Especificación | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
|---|---|---|---|---|---|
| Componente | tanrei-callout | TanreiCallout | TanreiCallout | TanreiCallout | Callout |
title · Propiedad | headline | title | title | title | title |
status · Propiedad | status | status | status | status | status |
statusLabel · Propiedad | statusLabel | statusLabel | statusDescription | statusSemanticLabel | statusAccessibilityLabel |
variant · Propiedad | variant | variant | variant | variant | variant |
size · Propiedad | size | size | size | size | size |
live · Propiedad | live | isLive | live | live | live |
closable · Propiedad | closable | isClosable | closable | closable | closable |
closeLabel · Propiedad | closeLabel | closeLabel | closeDescription | closeSemanticLabel | closeAccessibilityLabel |
open · Propiedad | open | isPresented | visible | visible | open |
dismiss · Evento | dismiss | onDismiss | onDismiss | onDismiss | onDismiss |
| Notas | <tanrei-callout> with the body as light-DOM children, the glyph in the icon slot, the title in the title slot (<p slot="title">, or <h3 slot="title"> where it is a heading) or the headline attribute (HTML's global title attribute would show a tooltip over the whole block, as the snackbar's and the app bar's), and Buttons or links in the actions slot. statusLabel and closeLabel are the status-label and close-label attributes. open is a boolean property that defaults to true; the open attribute spells it, and open="false" is how markup starts a callout closed. The host is display: block with no margin, role="note" and aria-labelledby naming the title, set through ElementInternals where axe can see it and as attributes otherwise; with live the host's role is status or alert by status, and the announcement is made through a visually hidden live region in the shadow root that exists from the element's first render, so that a callout opened later is announced (CLO-21). statusLabel is drawn as visually hidden text before the title in the shadow root, followed by a comma and a space; the glyph is aria-hidden. The body takes the form's content color and the size's text style through inherited color and font, so text placed directly in the element is styled, and a body that is rendered Markdown is wrapped by the product in <div class="tanrei-prose" data-measure="false"> with the callout's data-size (prose re-enters inside a Tanrei element). The glyph's opacity is applied to its color (a mix with transparent), never as an element's opacity. The close button is a <tanrei-button size="small"> with the close glyph in its icon slot and close-label as its label, in the shadow root (part close-button); the callout gives it the variant --tanrei-comp-callout-close-button-variant names and, in a look with a fill, the tone of its form (the form's body-color custom property) through the Button's internal channel, after each update (CLO-10). Under forced-colors: active the container takes a CanvasText border of the outline width (CLO-24). The stylesheet of @tanrei/web gives tanrei-callout:not(:defined) display: block, so the content keeps its place before the element is defined. dismiss is a CustomEvent. | TanreiCallout(_ title: String? = nil, status:, statusLabel:, variant:, size:, isLive:, isClosable:, closeLabel:, isPresented:, icon:, onDismiss:) { body } actions: { … }, the body and the actions as @ViewBuilders, the glyph by name through icon:, and a second initializer whose title is a @ViewBuilder (the title slot; .accessibilityAddTraits(.isHeader) is the product's). isPresented is a Binding<Bool> that defaults to a constant true. The container is an accessibility container labelled by the title or statusLabel; a live callout posts AccessibilityNotification.Announcement at default priority, or high for warning and error. | TanreiCallout(title, status, statusDescription, variant, size, live, closable, closeDescription, visible, icon, onDismiss, titleContent, actions) { body }, the body, titleContent and actions as composable lambdas, the glyph by name through icon. visible is hoisted state: the close button calls onDismiss and the product sets it. The container merges no descendants and carries paneTitle-free semantics: a content description of the status description on a leading invisible node, and for a live callout liveRegion polite or assertive by status. | TanreiCallout(title: …, status:, statusSemanticLabel:, variant:, size:, live:, closable:, closeSemanticLabel:, visible:, icon:, titleWidget:, actions:, onDismiss:, child:), the body as child, the title slot as titleWidget, the actions as a list of widgets, the glyph by name through icon. visible is the product's state; the close button calls onDismiss. A Semantics(container: true, label:) over the block, with liveRegion: true for a live callout and SemanticsService.announce with its assertiveness for warning and error. | <Callout title="…" status="warning">…</Callout>; the body is children, the title slot is the titleContent prop, the actions are the actions prop (elements), and the glyph is the icon prop (a glyph name). open is controlled when given, with onDismiss. A live callout sets accessibilityLiveRegion (polite or assertive) on Android and calls AccessibilityInfo.announceForAccessibility on iOS. Follows the app's direction where an ancestor's is not known. |
Tokens
| Token | Alias de | Valor resuelto (claro) |
|---|---|---|
--tanrei-comp-callout-actions-gap | sys.space.space150 | 12px |
--tanrei-comp-callout-actions-item-gap | sys.space.space100 | 8px |
--tanrei-comp-callout-body-color-outlined | sys.color.on-surface | |
--tanrei-comp-callout-body-color-tonal | sys.color.on-secondary-container | |
--tanrei-comp-callout-close-button-variant | — | 1 |
--tanrei-comp-callout-container-color-outlined | — | |
--tanrei-comp-callout-container-color-tonal | sys.color.secondary-container | |
--tanrei-comp-callout-container-gap | sys.space.space100 | 8px |
--tanrei-comp-callout-container-padding-block | sys.space.space150 | 12px |
--tanrei-comp-callout-container-padding-inline | sys.space.space200 | 16px |
--tanrei-comp-callout-container-padding-inline-end-with-close | sys.space.space100 | 8px |
--tanrei-comp-callout-container-shape | sys.shape.corner.medium | 8px |
--tanrei-comp-callout-error-body-color-outlined | comp.callout.body.color.outlined | |
--tanrei-comp-callout-error-body-color-tonal | sys.color.on-error-container | |
--tanrei-comp-callout-error-container-color-outlined | comp.callout.container.color.outlined | |
--tanrei-comp-callout-error-container-color-tonal | sys.color.error-container | |
--tanrei-comp-callout-error-icon-color-outlined | sys.color.error | |
--tanrei-comp-callout-error-icon-color-tonal | sys.color.error | |
--tanrei-comp-callout-error-title-color-outlined | comp.callout.error.body.color.outlined | |
--tanrei-comp-callout-error-title-color-tonal | comp.callout.error.body.color.tonal | |
--tanrei-comp-callout-icon-color-outlined | sys.color.on-surface-variant | |
--tanrei-comp-callout-icon-color-tonal | comp.callout.body.color.tonal | |
--tanrei-comp-callout-icon-gap | sys.space.space150 | 12px |
--tanrei-comp-callout-icon-opacity | — | 0.85 |
--tanrei-comp-callout-icon-size | sys.icon.small | 20px |
--tanrei-comp-callout-info-body-color-outlined | comp.callout.body.color.outlined | |
--tanrei-comp-callout-info-body-color-tonal | sys.color.on-info-container | |
--tanrei-comp-callout-info-container-color-outlined | comp.callout.container.color.outlined | |
--tanrei-comp-callout-info-container-color-tonal | sys.color.info-container | |
--tanrei-comp-callout-info-icon-color-outlined | sys.color.info | |
--tanrei-comp-callout-info-icon-color-tonal | sys.color.info | |
--tanrei-comp-callout-info-title-color-outlined | comp.callout.info.body.color.outlined | |
--tanrei-comp-callout-info-title-color-tonal | comp.callout.info.body.color.tonal | |
--tanrei-comp-callout-outline-color | sys.color.outline-variant | |
--tanrei-comp-callout-outline-width | sys.border.hairline | 1px |
--tanrei-comp-callout-success-body-color-outlined | comp.callout.body.color.outlined | |
--tanrei-comp-callout-success-body-color-tonal | sys.color.on-success-container | |
--tanrei-comp-callout-success-container-color-outlined | comp.callout.container.color.outlined | |
--tanrei-comp-callout-success-container-color-tonal | sys.color.success-container | |
--tanrei-comp-callout-success-icon-color-outlined | sys.color.success | |
--tanrei-comp-callout-success-icon-color-tonal | sys.color.success | |
--tanrei-comp-callout-success-title-color-outlined | comp.callout.success.body.color.outlined | |
--tanrei-comp-callout-success-title-color-tonal | comp.callout.success.body.color.tonal | |
--tanrei-comp-callout-title-color-outlined | comp.callout.body.color.outlined | |
--tanrei-comp-callout-title-color-tonal | comp.callout.body.color.tonal | |
--tanrei-comp-callout-title-gap | sys.space.space50 | 4px |
--tanrei-comp-callout-warning-body-color-outlined | comp.callout.body.color.outlined | |
--tanrei-comp-callout-warning-body-color-tonal | sys.color.on-warning-container | |
--tanrei-comp-callout-warning-container-color-outlined | comp.callout.container.color.outlined | |
--tanrei-comp-callout-warning-container-color-tonal | sys.color.warning-container | |
--tanrei-comp-callout-warning-icon-color-outlined | sys.color.warning | |
--tanrei-comp-callout-warning-icon-color-tonal | sys.color.warning | |
--tanrei-comp-callout-warning-title-color-outlined | comp.callout.warning.body.color.outlined | |
--tanrei-comp-callout-warning-title-color-tonal | comp.callout.warning.body.color.tonal | |
--tanrei-comp-callout-body-typescale-large | sys.typescale.body-large | 400 16px/1.625 |
--tanrei-comp-callout-body-typescale-medium | sys.typescale.body | 400 14px/1.5714 |
--tanrei-comp-callout-title-typescale-large | sys.typescale.heading-5 | 500 16px/1.5 |
--tanrei-comp-callout-title-typescale-medium | sys.typescale.heading-6 | 500 14px/1.4286 |
Fixtures
Representaciones canónicas. Todas las plataformas capturan cada fixture con el mismo identificador para poder comparar los resultados.
variant: tonal (27)
tonal
{} tonal-info
status: info statusLabel: Information variant: tonal tonal-warning
status: warning statusLabel: Warning variant: tonal tonal-error
status: error statusLabel: Error variant: tonal tonal-success
status: success statusLabel: Success variant: tonal title
title: Sizes are minimums title-info
title: A revised spec, not yet on every platfor… status: info title-only
title: All checks passed status: success large
size: large large-title-info
title: A revised spec, not yet on every platfor… status: info size: large icon
title: Tip slots: icon icon-info
title: Experimental status: info slots: icon title-slot
status: info slots: title actions
title: The file changed on disk status: warning slots: actions closable
closable: true closeLabel: Close closable-title-actions
title: Three fields need attention status: error live: true closable: true closeLabel: Close slots: actions status-label
status: warning statusLabel: Warning live-success
status: success statusLabel: Success live: true long-body
title: A revised spec, not yet on every platfor… status: info long-title
title: The native platforms have not renamed th… status: warning closable: true closeLabel: Close tonal-info-rtl
title: ملاحظة status: info direction: rtl closable-actions-rtl
title: تغيّر الملف على القرص status: warning closable: true closeLabel: إغلاق direction: rtl slots: actions icon-rtl
title: التالي direction: rtl slots: icon docs-note
title: Note status: info size: large docs-tip
title: Tip size: large slots: icon docs-caution
title: Back up before you migrate status: warning size: large docs-danger
title: Danger status: error size: large variant: outlined (11)
outlined
variant: outlined outlined-info
status: info statusLabel: Information variant: outlined outlined-warning
status: warning statusLabel: Warning variant: outlined outlined-error
status: error statusLabel: Error variant: outlined outlined-success
status: success statusLabel: Success variant: outlined title-outlined-warning
title: Accessibility status: warning statusLabel: Warning variant: outlined large-outlined-error
status: error statusLabel: Error variant: outlined size: large icon-outlined
title: Tip variant: outlined slots: icon actions-outlined
variant: outlined slots: actions closable-outlined-info
status: info statusLabel: Information variant: outlined closable: true closeLabel: Close ltr-title-rtl
title: v2.1 beta status: success variant: outlined direction: rtl Generado a partir de specs/callout.spec.json, tokens/comp/callout.tokens.json, design/tokens/
Los tres se distinguen de una vez por todas por dónde se sitúan y cuánto tiempo permanecen:
| Tipo | Qué es | Dónde se sitúa | Cuánto permanece | Se anuncia |
|---|---|---|---|---|
| Snackbar | El resultado de algo que la aplicación acaba de hacer o que acaba de ocurrir. | Sobre el contenido, en el borde de la ventana. | Un momento, o hasta que se cierra. | Siempre. |
| Callout | Un aviso que forma parte del contenido. | En el flujo, donde lo pones. | Tanto como el contenido. | Solo cuando aparece en respuesta a algo (live). |
| Diálogo | Una pregunta que la persona debe responder antes de continuar. | Por encima de todo, con un velo. | Hasta que se responde. | Al recibir el foco. |
Un banner, es decir, un aviso para toda una página o pantalla situado sobre su contenido, no es una cuarta cosa. Es un callout que colocas sobre el contenido de esa región, por lo general con live y con una acción o un botón de cierre. Ponlo donde quede primero en el orden de lectura de la región a la que se refiere.
Un mensaje bajo un solo campo (este valor no es una fecha) tampoco es un callout: es el texto de apoyo del propio campo.
variant |
Qué dibuja | Úsalo para |
|---|---|---|
tonal (predeterminado) |
Un relleno discreto. | La mayoría de los callouts. |
outlined |
Sin relleno y con una línea fina. | Un callout sobre una superficie con tinte o dentro de una tarjeta con relleno, donde un relleno desaparecería, y muchos callouts muy juntos. |
La línea fina es la única línea fina del sistema en todos los estados. Un estado nunca le da color.
status es default, info, warning, error o success: los nombres que usan el snackbar y el tag, con el significado que tienen en todo el sistema. Un estado dibuja sus colores y su glifo (info, warning, error, check_circle) y decide cómo se anuncia un callout activo. No cambia nada más.
| Qué estás escribiendo | Usa |
|---|---|
| Una nota: algo que conviene saber | status="info" |
| Una precaución: algo que requiere atención | status="warning" |
| Un peligro: algo que va a salir mal | status="error" |
| Un consejo: una recomendación que quien lee puede seguir | status="default", el glifo lightbulb en el slot icon y el título «Consejo» |
Un consejo no es un éxito: nada ha salido bien. El slot icon admite cualquier glifo del conjunto de iconos, con estado o sin él, así que «experimental» y «nuevo en esta versión» tampoco necesitan un valor nuevo. La palabra va en el título.
size |
Título | Cuerpo | Úsalo para |
|---|---|---|---|
medium (predeterminado) |
14 sobre un interlineado de 20 | 14 sobre 22 | Un callout entre controles: un formulario, un panel, un diálogo. |
large |
16 sobre 24 | 16 sobre 26 | Un callout en una página cuyo propósito es el texto. |
Son los dos tamaños de la prosa. Solo cambian los estilos de texto: los márgenes interiores, el glifo y el botón de cierre son los mismos.
headline es texto sin más y nunca un encabezado. La mayoría de los títulos son el rótulo de una nota, y una página cuyo esquema enumera «Nota» cinco veces sale perdiendo. Cuando un callout abre una parte de la página a la que la gente navega, pon en el slot title un encabezado del nivel que necesite tu esquema. El callout lo dibuja como cualquier título y no cambia ni su rol ni su nivel.
En una página que se renderiza en un servidor, da el título en el slot title: un atributo headline lo dibuja el elemento, así que no se muestra antes de que el elemento esté definido.
El texto colocado directamente en el elemento toma el estilo de texto y el color del callout. Los bloques de contenido extenso (párrafos, listas, una tabla, un bloque de código) van en una prosa del tamaño del callout y sin medida:
<tanrei-callout status="info">
<div class="tanrei-prose" data-measure="false">…Markdown renderizado…</div>
</tanrei-callout>La prosa no trae color, así que se lee sobre cualquier relleno, y sus enlaces van subrayados. Un componente colocado en el cuerpo conserva sus propios estilos. Un callout dentro de una prosa que mantiene una medida se limita a la medida como un bloque de texto; en cualquier otro lugar ocupa la anchura que se le da.
Las acciones son tus propios botones o enlaces, uno o dos. Usa botones outlined o text: un botón tonal tiene el relleno del callout tonal sin estado, y ahí no se distingue como botón. El callout los dispone en una fila que salta de línea y no hace nada más: no se cierra cuando se pulsa uno.
closable dibuja un botón de cierre: un botón pequeño, solo con icono, que recibe su nombre de close-label y su variante de --tanrei-comp-callout-close-button-variant (tonal en el sistema predeterminado). En un callout tonal se dibuja en el color de texto del propio callout —un círculo de ese color hecho translúcido, con el glifo dentro en el mismo color—, de modo que se ve sobre el relleno de cualquier estado; en un callout outlined, que no tiene relleno, es el botón tal como es en cualquier otra parte. Responde al paso del puntero, al foco y a la pulsación como cualquier botón. Al pulsarlo, open pasa a ser false y se emite dismiss. El callout nunca se cierra por sí solo y no responde a Escape. Cuando una persona cierre uno, recuérdalo: un callout que se puede cerrar y vuelve en cada visita es ruido. Una precaución que matiza el contenido que tiene al lado no debería poder cerrarse.
live es para un callout que aparece o cambia mientras la persona trabaja: un resumen de los errores de un formulario después de enviarlo, un aviso de que el archivo ha cambiado por debajo. Mantenlo en la página con open="false" y define open cuando corresponda.
Un callout activo, mostrado en respuesta a una pulsación
<tanrei-callout id="errors" live open="false" status="error" headline="Hay tres campos que revisar">
Escribe un nombre, elige una fecha de inicio e indica una dirección que pueda recibir correo.
</tanrei-callout>
<script type="module">
form.addEventListener('submit', (event) => {
if (!form.checkValidity()) {
event.preventDefault();
document.querySelector('#errors').open = true; // se anuncia una vez, de forma asertiva
}
});
</script>Un callout activo se anuncia una vez cuando se muestra y cuando cambian su título, su cuerpo o su estado: de forma cortés para default, info y success, y de forma asertiva para warning y error. Uno que ya está en el marcado de la página cuando esta se carga no se anuncia en ese momento.
En la web, un callout activo que tu script añade a la página después de que se haya cargado sí se anuncia. El elemento no puede distinguir un callout añadido en respuesta a algo de uno añadido con una vista nueva de una aplicación de página única, así que, para un aviso que simplemente forma parte de una vista nueva, no pongas live.
El cuerpo, el slot del título y las acciones son hijos del propio elemento, así que están en el documento: la búsqueda en la página los encuentra, se traducen, se seleccionan y se leen sin script. @tanrei/web/callout.css da a un callout que aún no está definido la caja que tendrá (sus márgenes interiores, sus estilos de texto, el sitio de su glifo y de su botón de cierre, y nada en absoluto con open="false"), de modo que nada se mueve cuando el elemento se define. Hasta entonces se muestra sin el relleno, el glifo ni el botón de cierre.
- Di el estado con palabras. «Advertencia: haz antes una copia de seguridad» no necesita nada más; «Accesibilidad» en una advertencia necesita
status-label="Advertencia". - Usa los estados con el significado que tienen en todas partes. Una recomendación no es un éxito.
- Pon una sola lista de puntos en un solo callout en lugar de varios callouts seguidos.
- No uses un callout activo para una nota que está escrita en la página. El contenido estático no es una alerta.
- No anides callouts ni apiles varios en la parte superior de una página: los avisos del mismo peso, uno junto a otro, se anulan entre sí.
- No muevas el foco a un resumen de errores y, además, lo anuncies. Mover el foco al resumen conviene a un formulario largo cuyo primer error puede quedar fuera de la pantalla; anunciarlo y mover el foco al primer campo con error conviene a uno corto.
- No dependas del color para transmitir el estado. Con colores forzados, todos los callouts son un borde y un texto en el color del texto.
- Rol
note- Etiquetado
- A callout that is not live is a note (the note role on the web), read where it stands, named by its title or, without one, by statusLabel. A live callout is a live region instead: polite in the default, info and success forms (the status role on the web) and assertive in the warning and error forms (the alert role on the web), announced once when it is shown after its page was presented and when its content changes. In both, statusLabel is exposed as text before the title and the body; the glyph is hidden. A title given as text is plain text; a heading in the title slot keeps its level. The close button's name is closeLabel. Actions are the product's own controls with their own names.
- Objetivo mínimo
- El área de pulsación cumple el tamaño mínimo de objetivo aunque el tamaño visual sea menor. minimum 32px · pointer 44px · spacing 8px · touch 48px
Teclado
| Teclas | Acción |
|---|---|
| Tab | Reaches, at the callout's place in the page, the links and controls of the body, then the actions, then the close button. The callout itself is not a stop, and showing one never moves focus. |
| Enter / Space | Activates the focused close button: the callout closes and focus returns to where it was before it entered the callout (CLO-12). |
Notas
- Static content is not an alert. A callout written into a page (a note in documentation, a caution above a procedure) must not interrupt a screen reader when the page loads or be repeated as a status message: it is read in order, as the paragraph before it is. live is for what appears or changes in answer to something, and even then a callout that the page is first presented with is not announced (CLO-21).
- A summary of a form's errors is a live callout with the error status, shown after the submit. Whether focus also moves to it is the product's decision, by its own means (the callout takes no focus by itself): moving focus to the summary suits a long form whose first error may be off screen; announcing it and moving focus to the first field in error suits a short one. Do not do both.
- A notice for a whole page or screen (a banner: the connection is lost, the file changed on disk, a trial ends) is a callout placed by the product above that region's content, live, usually with an action or a close button. Put it where it comes first in reading order for the region it concerns.
- WCAG 1.4.1 (use of color): a status is never told by color alone. A status form draws the status's glyph, a shape of the icon set, and the status is in the title's words or in statusLabel (CLO-20). The component cannot tell whether a title says its status, so that is the product's to check: "Accessibility" on a warning needs statusLabel "Warning"; "Warning: not published yet" does not.
- WCAG 1.3.1 (info and relationships): the callout does not decide whether its title is a heading. Most titles are labels of a note and should stay text, or the page's outline fills with entries such as "Note". Where a callout does open a part of the page that people navigate to, the product gives a heading of the right level in the title slot.
- WCAG 1.4.3 and 1.4.11 (contrast) in the default system: the title and the body are a role on its paired role (on-secondary-container on secondary-container, on-info-container on info-container, on-surface on a surface), each held to 4.5:1 by the token invariants. The glyph is drawn at an opacity of its color, so its contrast is that of the color as drawn: at least 3.5:1 on its own status container and on every surface, in every scheme. A link in the body is the system's link color, underlined: at least 4.6:1 on every tonal container (7.2:1 in the high-contrast schemes). The outlined look's edge is decorative.
- Actions are the product's Buttons. A filled or a tonal Button brings its own fill and keeps its own contrast; the label of an outlined or a text Button sits on the callout's fill, where the default system's primary keeps at least 13:1 on every tonal container. A tonal Button has the fill of the tonal callout without a status and cannot be seen as a button there: use outlined or text. The focus indicator of a product's control in the body or the actions is the system's focus color, at least 4.6:1 on every tonal container of the default system.
- A closable callout that returns on every visit is noise: when the person closes one, the product should remember it. The callout only reports the close (dismiss).
- Do not nest callouts, and do not stack several at the top of a page: two notices of the same weight side by side cancel each other. One callout may hold a list of points.
- Forced colors (CLO-24): a tonal callout loses its fill, so every look gains an edge in the text color. Statuses then differ by glyph and words alone.
- Web: the body, the title slot and the actions are light-DOM children of `<tanrei-callout>`, so they stay in the document: they are found by search in the page, translated, selected and read without script, and before the element is defined they show as plain blocks in the page's own text styles, without the fill, the glyph and the close button. A title given by the `headline` attribute is not shown until the element is defined; content pages should use the title slot.
- The callout itself has no states: nothing about its container, its text or its glyph answers a pointer, a press or focus. Its close button is a Button, and answers them as every Button does.
- WCAG 1.4.11 (non-text contrast) and 2.4.13 (focus appearance) for the close button: in a filled look it is drawn in the tone of the fill (BTN-45), its glyph in the fill's content color (the body color, held to 4.5:1 on the fill by the token invariants) over a container of that color at comp.button.tone.container.opacity. In the default system the glyph keeps against that blend, in every status, at least 9.5:1 at rest in the light schemes and 7.7:1 in the dark ones, and at least 6.0:1 hovered, focused or pressed in every scheme; the focus indicator's outer stroke, in the same color on the callout's fill, keeps at least 12:1. In the outlined look it is the variant's own Button on the surface, whose glyph the Button's own tokens hold.
Generado a partir de specs/callout.spec.json, tokens/sys/measure.tokens.json
- Es una nota (
role="note"), que recibe su nombre del título, o destatus-labelcuando no tiene título. Conlivees, en cambio, una región activa:role="status", orole="alert"para una advertencia o un error. status-labelse lee antes del título y del cuerpo como una frase aparte («Advertencia, …») y nunca se dibuja. Se ignora mientrasstatusesdefault.- El glifo queda oculto para la tecnología de apoyo.
- Un título dado como texto es texto sin más. Un encabezado en el slot
titleconserva su nivel. - No es una parada en el orden del foco y nunca mueve el foco. Tab llega a los enlaces y controles del cuerpo, después a las acciones y después al botón de cierre.
- Cuando se cierra mientras el foco está dentro, el foco vuelve al elemento que lo tenía antes de entrar en el callout, de modo que el siguiente Tab llega a lo que venía a continuación.
- El botón de cierre es un botón: su área de pulsación alcanza el objetivo mínimo y, en un callout tonal, su glifo y su anillo de foco van en el color de texto del callout, que mantiene al menos 6:1 frente al botón en todos los estados y esquemas de color del sistema predeterminado.
- Con el texto ampliado, todo salta de línea y crece; el glifo y el botón de cierre se quedan en la primera línea.
- Con colores forzados, todos los aspectos ganan un borde en el color del texto, y el glifo se dibuja entero.
- En un diseño de derecha a izquierda, el glifo pasa a la derecha y el botón de cierre a la izquierda, un glifo que el conjunto de iconos marca para ello se refleja, y un título escrito de izquierda a derecha conserva su propio orden.
- Las compilaciones de depuración notifican una variante, un tamaño o un estado desconocidos, un callout sin título ni cuerpo, un estado que no se dice con palabras, un botón de cierre sin nombre y un
status-labelsin estado.
- Comprueba que las palabras de cada callout digan su estado. El componente no puede saber si un título lo hace.
- Escribe
status-labelyclose-labelen el idioma de la página. - Usa
livesolo para un callout que aparece o cambia en respuesta a algo. - Da a cada acción una etiqueta que quepa. La etiqueta de un botón ocupa una sola línea, así que, en una pantalla estrecha con el texto ampliado, una etiqueta larga puede ser más ancha que el callout.