Figura
Coloca una cosa que se mira, una imagen, un gráfico, una muestra o un ejemplo en vivo, en un escenario propio, con marco o sin él, con una leyenda que dice qué muestra y, de forma opcional, un título con tus controles encima y un bloque unido debajo.
- Categoría
- Contención
- Tokens
comp.figure- Nivel
- Base
- Web
tanrei-figureschedule - SwiftUI
TanreiFigureradio_button_unchecked - Jetpack Compose
TanreiFigureradio_button_unchecked - Flutter
TanreiFigureradio_button_unchecked - React Native
Figureradio_button_unchecked
Generado a partir de docs/status/status.json, specs/figure.spec.json
Outlined, filled y plain
Una figura muestra una cosa que se mira en lugar de leerse: una imagen en un artículo, un gráfico en un informe, una vista previa de lo que producirá un ajuste, una muestra. La separa de lo demás y dice qué es. Los marcos que rodean los ejemplos en vivo de este sitio son figuras.
No es una tarjeta. Una tarjeta agrupa contenido y acciones sobre un mismo asunto y puede pulsarse entera. Una figura muestra una sola cosa, nunca se pulsa y pone su leyenda fuera de su marco.
En la web es <tanrei-figure> alrededor de un <figure> nativo. El elemento no tiene shadow root, así que la figura y su <figcaption> son los del propio documento: se leen sin script, los leen un rastreador y un modo de lectura, y el navegador les da nombre. Las demás plataformas todavía no la han implementado.
<link rel="stylesheet" href="@tanrei/web/figure.css" />
<tanrei-figure>
<figure>
<div data-part="frame">
<header>
<p data-part="title">Ingresos por trimestre</p>
<div data-part="actions">
<tanrei-button variant="text" label="Abrir en una pestaña nueva"><span slot="icon">open_in_new</span></tanrei-button>
</div>
</header>
<div data-part="stage">
<img src="revenue.svg" alt="Un gráfico de barras: los ingresos suben en todos los trimestres." />
</div>
</div>
<figcaption>Todas las regiones crecieron; la región norte fue la que más creció.</figcaption>
</figure>
</tanrei-figure>
<script type="module">
import '@tanrei/web/components/figure';
</script>import { Figure } from '@tanrei/react';
import '@tanrei/web/figure.css';
<Figure variant="plain">
<figure>
<img src={photo.src} alt={photo.alt} />
<figcaption>{photo.caption}</figcaption>
</figure>
</Figure>@tanrei/web/figure.css dibuja toda la figura antes de que se ejecute ningún script, así que una página de figuras no se mueve cuando llega el script. El elemento añade por sí solo la misma hoja de estilos a la página.
| Parte | En la web |
|---|---|
| El marco | <div data-part="frame">, el primer hijo del <figure>. Contiene la cabecera, el escenario y el bloque adjunto. |
| El título | Un elemento con data-part="title" en el <header> del marco: un <p>, o el encabezado que necesite el esquema de tu página. |
| Las acciones | <div data-part="actions"> en el <header>, alrededor de tus propios controles. |
| El escenario | <div data-part="stage">, alrededor de lo que se muestra. |
| El bloque adjunto | Cualquier elemento con data-part="attachment" después del escenario: un bloque de código, una tabla, una lista de descripciones. |
| La leyenda | El <figcaption>, después del marco. |
Todas las partes salvo el escenario son opcionales. Un <img>, <picture>, <video>, <svg> o <canvas> por sí solo puede ocupar el lugar del elemento del escenario, y también se dibuja una figura sin ningún elemento de marco, <figure><img …><figcaption>…</figcaption></figure>, como la escribe un renderizador de Markdown: la imagen es entonces su propio marco.
A un <tanrei-figure> que no contiene ningún <figure> se le da uno cuando se define el elemento. Sus hijos pasan a ser el escenario, salvo los que nombran una parte con slot (title, actions, caption, attachment). Los atributos headline y caption se escriben como el título y la leyenda.
<tanrei-figure headline="Variantes" caption="Un botón filled.">
<tanrei-button variant="filled">Guardar</tanrei-button>
</tanrei-figure>Esta forma es más corta, y solo se dibuja una vez que el script se ha ejecutado. Escribe tú las partes donde la página no deba moverse, y también con un framework que sea dueño de los hijos del elemento (React), porque el elemento los mueve.
Un título, un control, un bloque unido y una leyenda
Variantes
<tanrei-button variant=“filled”>Filled</tanrei-button>Sin margen interior: lo que se muestra llega hasta los bordes del marco
Más ancho que su escenario: se desplaza dentro de él, y el escenario es una parada de foco
Cuadrícula, puntos, una cuadrícula que se desvanece hacia el centro y un tablero de ajedrez
Anatomía
| Parte | Descripción |
|---|---|
1 container | The frame: the shape that holds the header, the stage and the attachment, with a card's corners. Filled with the surface and edged in the outlined look, filled with a quiet tone in the filled look, and neither filled nor edged in the plain 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 frame. |
3 header · opcional | The row at the top of the frame that holds the title and the actions. Drawn only where the figure has one of them. |
4 title · opcional | A short line that names what is shown, at the start of the header. Text, never a heading by itself. |
5 actions · opcional | The product's own controls at the end of the header (which variant, which theme, open it elsewhere). The figure lays them out and nothing else. |
6 stage | Where the thing shown stands: the product's content, padded inside the frame or reaching its edges, scaled down where it can shrink and scrolled sideways inside the stage where it cannot. |
7 pattern · opcional | The ground pattern behind what is shown, where the product asks for one: grid lines, a dot grid, a grid that fades toward the centre, or a checkerboard, drawn across the stage's box over the frame's fill and under the content. Decoration only. |
8 attachment · opcional | The product's block joined under the stage, inside the frame: the code an example was made from, the data of a chart, the facts about a specimen. |
9 divider · opcional | The line between the header and the stage and between the stage and the attachment, while the separation is a divider and the look has a frame. |
10 caption · opcional | The text below the frame that says what is shown, in secondary text on the surface the figure sits on. |
11 focus-ring · opcional | The system's focus indicator inside the stage's edge, drawn only while the stage scrolls and has keyboard focus. |
Propiedades
| Propiedad | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
title | string | "" | The title: a short line above the stage that names what is shown ("Variants", "Revenue by quarter"). Plain text, never a heading; the title slot takes the product's own content in its place. It is the figure's accessible name where it is given. |
caption | string | "" | The caption: the text below the frame that says what is shown. The caption slot takes the product's own content in its place (a caption with a link, inline code or a tag). It is the figure's accessible name where there is no title, and its description where there is one. |
label | string | "" | The accessible name of a figure that draws neither a title nor a caption, in the product's language. Never drawn. Ignored where a title or a caption is given. |
variant | outlined | filled | plain | "outlined" | How the stage is set apart. outlined: the surface inside one hairline, the default. filled: a quiet tone and no edge, where one more line would crowd the page. plain: no fill, no edge, no padding and no line, for a picture that is its own frame. A design system may add values. |
inset | boolean | true | Whether the stage is padded inside the frame. True for a specimen or a live example, which needs room around it; false for a picture, a chart or a map that should reach the frame's edges and be clipped by its corners. The plain look has no frame to be inset from and is never padded. |
separation | auto | divider | gap | "auto" | How the parts inside the frame are told apart. auto takes comp.figure.separation, which follows the system's choice. divider draws a line between the header and the stage and between the stage and the attachment, the attachment flush with the frame. gap draws no line and stands the attachment inside the frame with its own shape. The plain look has no frame and draws neither. |
pattern | none | grid | dots | grid-fade | checkerboard | "none" | The ground pattern drawn behind what is shown, across the stage. none: the plain fill, the default. grid: lines in both directions, the ground of a layout or a design canvas. dots: a dot at every crossing of that grid, a quieter ground for a drawing or a diagram. grid-fade: the grid, clear around the centre and growing toward the edges, so that a specimen at the centre stands on the plain fill and the grid frames it. checkerboard: small squares, the ground that shows where a picture is transparent. Decoration only: it says nothing to assistive technology, and the plain look and forced colors draw none. |
Slots
| Slot | Descripción |
|---|---|
default | What is shown, in the stage: a picture, a video, a chart, a diagram, a specimen, a live example of the product's own components. The figure does not style, crop, mirror or operate it. |
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 figure draws it in the title's style and changes neither its role nor its level. |
actions | The controls at the end of the header: the product's own icon-only Buttons, tabs, a select or links. The figure lays them out in a row and does nothing else to them. |
caption | The product's own caption content in place of the caption prop: text with links, inline code, a keyboard shortcut or a tag. |
attachment | The block joined under the stage, inside the frame: a code block, a table, a description of the specimen. It is the product's component and keeps its own styles. |
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 |
|---|---|
FIG-1 | THE figure SHALL draw, from top to bottom, a frame that holds its header where it has one (FIG-7), its stage and its attachment where it has one (FIG-11), and below the frame its caption where it has one (FIG-10); the frame SHALL have corners comp.figure.container.shape eased by sys.shape.corner-smoothing, SHALL clip what it holds to those corners, SHALL be exactly as tall as what it holds, with no height and no minimum height of its own, and SHALL draw no elevation. |
FIG-2 | WHILE variant is outlined THE figure SHALL fill its frame with comp.figure.outlined.container.color and draw an edge comp.figure.outline.width wide in comp.figure.outline.color inside the frame's size, following its corners, without changing the frame's size or the place of what it holds; WHILE variant is filled it SHALL fill the frame with comp.figure.filled.container.color and draw no edge; WHILE variant is plain it SHALL draw no fill (comp.figure.plain.container.color), no edge, no padding and no line, so that what is shown is its own frame, and SHALL still clip the stage to comp.figure.container.shape. |
FIG-3 | THE figure SHALL place the content of its default slot in the stage and draw nothing of its own there, between the frame's fill and that content or over it, but the ground pattern the product asks for (FIG-26), under the content. WHILE inset is true and variant is not plain THE stage SHALL be padded by comp.figure.stage.padding-block above and below and comp.figure.stage.padding-inline before and after; WHILE inset is false or variant is plain THE stage SHALL have no padding, so that the content reaches the frame's edges. WHILE variant is outlined or filled THE figure SHALL hand the content comp.figure.content.color as the platform's inherited foreground and SHALL place content narrower or shorter than the stage at the stage's centre; WHILE variant is plain it SHALL hand no color and SHALL place content narrower than the stage at the stage's start edge, in line with the text around the figure. Several pieces of content SHALL be stacked in the order given with no space of the figure's between them: how several specimens are arranged is the product's layout. |
FIG-4 | WHEN content that has proportions of its own and can shrink — a picture, a video, a drawing — is wider than the stage's inner width THE figure SHALL scale it down to that width with its proportions kept (PRS-15), and SHALL NOT scale any content above its own size, crop it or stretch it: an aspect ratio and how a picture fills a box are the content's own. |
FIG-5 | WHEN content that cannot shrink is wider than the stage's inner width THE stage SHALL scroll it sideways inside its own box, beginning at the start edge and with that content placed at the start edge rather than at the centre, the stage's inline padding scrolling with the content so that its last part can be brought clear of the frame's edge; the header, the attachment and the caption SHALL NOT scroll with it, the figure SHALL never be wider than its layout and SHALL never make what holds it scroll sideways, and THE stage SHALL NOT scroll up and down: it is as tall as its content. |
FIG-6 | WHILE the stage scrolls (FIG-5) THE stage SHALL be one stop in the focus order, before anything inside it that takes focus, exposed as a group that carries the figure's name (FIG-16); WHILE it has keyboard focus it SHALL draw the system's focus indicator inside its edge — sys.focus.outer-width wide in the color role focus-ring, set in from the edge by sys.focus.offset so that nothing clips it, following the frame's corners where the stage meets them, and never animated — and the left and right arrow keys, Home and End SHALL scroll it as the platform scrolls a region, the arrow keys moving the view left and right in either layout direction; focus gained by pointer or touch SHALL NOT show the indicator; WHILE the stage does not scroll it SHALL NOT be a stop in the focus order and SHALL expose no group of its own. |
FIG-7 | WHERE the figure has a title (FIG-8) or content in its actions slot THE figure SHALL draw a header at the top of the frame: one row with the title at the start and the actions at the end, comp.figure.header.gap apart, padded by comp.figure.header.padding-block above and below, by comp.figure.header.padding-inline at the start, and at the end by comp.figure.header.padding-inline-end-with-actions where it holds actions and by comp.figure.header.padding-inline where it does not; the title SHALL take the room the actions leave and wrap inside it, the actions SHALL keep their own sizes, and WHEN the actions and one word of the title no longer fit in one row THE actions SHALL move to a row of their own below the title, at the start edge, comp.figure.header.gap below it. WHERE the figure has neither THE figure SHALL draw no header, no space for one and no line under one. |
FIG-8 | THE figure SHALL draw its title — the content of the title slot where it holds any, and the title prop otherwise — in comp.figure.title.typescale and comp.figure.title.color, wrapping and never cut; the title prop SHALL be exposed as plain text and never as a heading, and content given in the title slot SHALL keep the role and the level the product gave it (a heading stays the heading it is) while it is drawn in the title's style. IF both the prop and the slot are given THE slot SHALL be drawn and the prop ignored. THE figure 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. |
FIG-9 | THE figure SHALL lay out the content of its actions slot in one row at the end of the header, in the order given, comp.figure.header.gap apart, each centred on the height of that row, and SHALL do nothing else to it: the controls keep their own sizes, colors, states, focus indicators, targets and names, the figure listens to none of their events, and what they change in the stage — its theme, its direction, the variant on show — is the product's own doing. |
FIG-10 | WHERE the figure has a caption — the content of the caption slot where it holds any, and the caption prop otherwise — THE figure SHALL draw it below the frame, comp.figure.caption.gap from it, at the figure's start edge, in comp.figure.caption.typescale and comp.figure.caption.color, wrapping inside the figure's inline size and never cut or limited to a number of lines; inline content the product gives in the slot (inline code, a keyboard shortcut, a tag) SHALL sit on the caption's baseline and keep its own styles, and a link in it SHALL be underlined at rest (PRS-17). IF both the prop and the slot are given THE slot SHALL be drawn and the prop ignored. THE caption SHALL be below the frame in every look and SHALL have no other place: text above the stage is the title. |
FIG-11 | WHERE the attachment slot holds content THE figure SHALL place it inside the frame, below the stage, across the frame's whole inline size, with no padding of the figure's around it, clipped by the frame's lower corners, and joined to the stage as the separation names (FIG-13); THE figure SHALL add no style to anything inside it: a block there that has a frame of its own (a code block, a table) is the product's to give in the form that suits the join. |
FIG-12 | THE figure SHALL tell the parts inside its frame apart as its separation names: WHILE separation is auto, as comp.figure.separation names, which follows sys.behavior.separation unless a design system sets it apart; WHILE separation is divider or gap, as that value names, whatever the tokens say. WHEN separation, or the token it follows, changes THE figure SHALL draw the other form at once, without animation, keeping the stage's scroll position; WHEN separation names a value the figure does not define THE figure SHALL treat it as auto and in debug builds report the unknown value. A platform that cannot draw a choice SHALL fall back to the first value, divider, and state that in its README. |
FIG-13 | WHILE the separation is divider and variant is not plain THE figure SHALL draw a line comp.figure.divider.thickness thick in comp.figure.divider.color across the frame's whole inline size between the header and the stage and between the stage and the attachment, wherever both parts of a pair are present, and SHALL place the attachment flush against that line and the frame's edges; WHILE the separation is gap and variant is not plain THE figure SHALL draw no line, SHALL leave the header's own padding as the only space between the header and the stage, and SHALL set the attachment in by comp.figure.attachment.gap from the stage above it and from the frame's inline and lower edges, where the attachment keeps the shape it has by itself. |
FIG-14 | WHILE variant is plain THE figure SHALL draw no line whatever the separation is, SHALL draw the header without inline padding so that the title begins at the figure's start edge, comp.figure.caption.gap above the stage, and SHALL place the attachment comp.figure.attachment.gap below the stage across the figure's whole inline size, where it keeps the shape it has by itself. |
FIG-15 | THE figure SHALL NOT take pointer, touch or keyboard input of its own, apart from the scrolling of FIG-5 and FIG-6, and SHALL NOT change anything it draws under a pointer, a press or focus: its frame, header, title and caption have no hovered, focused, pressed, selected or disabled state, it draws no state layer and no ripple, and it emits no event. Input over the stage, the actions and the attachment SHALL reach the content placed there, which stays as operable, as focusable and in the same focus order — the actions, then the stage's content, then the attachment's, then anything in the caption — as it would be outside a figure. |
FIG-16 | THE figure SHALL be exposed to assistive technology as a figure, or as a named group where the platform has no such role, whose name is its title where it has one, its caption where it has a caption and no title, and label otherwise; WHERE it has both a title and a caption THE caption SHALL be exposed as the figure's description and still be read as text in its place; THE figure SHALL NOT draw label. Everything in the header, the stage, the attachment and the caption SHALL stay exposed in that reading order, and THE figure SHALL neither supply nor replace the text alternative of a picture placed in the stage: that is the picture's own. IF title, caption and label are all empty THE figure SHALL be exposed without a name and in debug builds report that a figure has no name. |
FIG-17 | WHEN the title, the caption, the look, inset or the content of a slot changes THE figure SHALL draw and expose the new value at once, without a motion, keeping the stage's scroll position where the content still reaches it, and SHALL NOT announce the change by itself. |
FIG-18 | THE figure SHALL lay itself out as a block in the flow of its container: it SHALL take the whole inline size the container gives it — a page, a column of prose, a cell of the product's grid, a card, a tab's panel 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, and SHALL have no minimum width, no maximum width and no measure of its own. THE figure SHALL NOT float beside the text, stick to an edge while the content scrolls or raise itself above the page: where it stands, and how several figures are arranged side by side, is the product's layout. |
FIG-19 | WHILE the text size is enlarged THE figure SHALL grow its title and its caption with it, keep its paddings, gaps and lines, wrap, and grow in height; it 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 sideways scrolling of what holds it at a width of 320 points with text at 200 %: the actions move below the title (FIG-7) and content that cannot shrink scrolls inside the stage (FIG-5). |
FIG-20 | 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 figure SHALL draw an edge comp.figure.outline.width wide in the platform's text color inside its frame in the outlined and the filled looks, so that a look whose fill the mode removes is still a bounded stage, and no edge in the plain look, which has none to lose; it SHALL draw the lines of FIG-13 in that text color, its title and caption in that text color, links in the platform's link color and still underlined, and the focus indicator of FIG-6 in the platform's own color for focus, and no ground pattern (FIG-26) in any look, so that nothing but the person's own background stands behind the content; what is shown in the stage is the content's own to adapt. |
FIG-21 | WHERE the layout direction is right-to-left THE figure SHALL mirror the order of its header and apply its paddings by logical start and end, so that the title is at the right and the actions are at the left; SHALL draw the caption from the right edge; SHALL begin the stage's sideways scroll (FIG-5) at the right edge; and SHALL place a plain figure's narrow content (FIG-3) at the right edge. Top and bottom SHALL NOT change. THE figure SHALL NOT mirror, reorder or realign what is shown in the stage or in the attachment: a picture is never mirrored, and the direction of a live example is its own. |
FIG-22 | THE figure 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 figure is shown THE figure SHALL draw itself for the new direction at once, without a motion of its own, keeping what it shows. A direction the product sets on the stage's content alone (a live example drawn right-to-left inside a left-to-right page) SHALL change that content and nothing of the figure's. |
FIG-23 | THE figure SHALL lay out its title and its caption as text of their own direction, each isolated from the other and from the text around the figure: each takes the base direction of its first strong character, or the layout direction where it has none, so that a left-to-right name, an identifier, a number with its unit, a version and a date keep their own order in a right-to-left layout; THE figure SHALL still place each by the layout direction, not by the text's own, and SHALL wrap them, never cut them. |
FIG-24 | WHEN variant names a value that the active design system does not have THE figure SHALL render with the default variant's tokens, and in debug builds report the unknown value. |
FIG-25 | IF the default slot holds nothing THE figure SHALL draw nothing, take no space and expose nothing, and in debug builds report that a figure shows nothing: a title, a caption or an attachment alone is not a figure. IF label is not empty while a title or a caption is given THE figure SHALL ignore label. |
FIG-26 | WHILE pattern is not none and variant is not plain THE figure SHALL draw a ground pattern in comp.figure.pattern.color across the stage's whole box, over the frame's fill and under the stage's content, centred on the stage and still while the content scrolls (FIG-5): WHILE pattern is grid, lines comp.figure.pattern.line-thickness wide every comp.figure.pattern.spacing across and down; WHILE pattern is dots, dots comp.figure.pattern.dot-size across at the same spacing; WHILE pattern is grid-fade, that grid, clear from the stage's centre to comp.figure.pattern.clear-extent of the way to its edges and growing from there to full strength at its corners; WHILE pattern is checkerboard, squares of side comp.figure.pattern.checkerboard-size, alternately the frame's fill and comp.figure.pattern.color. The pattern SHALL be decoration: it SHALL take no input, be exposed to no assistive technology, be the same in either layout direction, and be covered by the content wherever the content is opaque. WHILE variant is plain THE figure SHALL draw no pattern, because the plain look has no stage to draw one on. IF pattern names a value the figure does not define THE figure SHALL draw none, and in debug builds report the unknown value. |
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-figure | TanreiFigure | TanreiFigure | TanreiFigure | Figure |
title · Propiedad | headline | title | title | title | title |
caption · Propiedad | caption | caption | caption | caption | caption |
label · Propiedad | label | accessibilityLabel | contentDescription | semanticLabel | accessibilityLabel |
variant · Propiedad | variant | variant | variant | variant | variant |
inset · Propiedad | inset | isInset | inset | inset | inset |
separation · Propiedad | separation | separation | separation | separation | separation |
pattern · Propiedad | pattern | pattern | pattern | pattern | pattern |
| Notas | Form: <tanrei-figure> is a custom element with **no shadow root**, wrapped around a native <figure> that stays in the light DOM, so that the figure and its caption are the document's own — read without script, by a crawler, by reader modes and by a screen reader as a figure with its <figcaption> (once the element is defined it names the figure by that caption itself, aria-labelledby, unless the product gave the <figure> an aria-label: one engine does not take the name from the caption): <tanrei-figure><figure><div data-part="frame"><header><p data-part="title">…</p><div data-part="actions">…</div></header><div data-part="stage">…</div><div data-part="attachment">…</div></div><figcaption>…</figcaption></figure></tanrei-figure>; every part but the stage is optional, and a lone <img>, <picture>, <video>, <svg> or <canvas> in place of the stage element is its own stage. Everything drawn comes from one stylesheet, @tanrei/web/figure.css, whose selectors start at tanrei-figure and are wrapped in :where(); it styles the page before the element is defined and without script, so a page of figures does not move when the script arrives, and the element adopts the same sheet into the root it is connected to. Props are attributes of the wrapper: variant, separation, pattern, label; inset is a boolean property that defaults to true and its attribute is the inverse flush, as the card's (an HTML boolean attribute cannot default to true). The title is the headline attribute (HTML's global title would show a tooltip over the whole figure, as on the callout); headline and caption are conveniences for a figure built by script or by the React wrapper, for which the element writes the parts above itself around its children. What the element adds once defined: aria-labelledby on the native figure naming the title where there are both a title and a caption, and aria-describedby naming the caption; aria-label from label; tabindex="0", role="group" and the same name on the stage while it scrolls sideways, removed when it does not (FIG-6); the resolved separation as a data-separation attribute where a container style query cannot be used; and the debug reports. A native <figure> with one <figcaption> and no title needs none of that. The ground pattern (FIG-26) is the stage's own background-image, a set of CSS gradients of the --tanrei-comp-figure-pattern-* tokens over a background-color of the look's fill, so it takes no element, no input and no place in the accessibility tree, stays in place while the stage scrolls, and stands behind a transparent lone picture too; the fading grid is the grid under a radial gradient of the fill. Under forced-colors: active the frame takes a CanvasText border in the outlined and filled looks, and the stage draws no pattern (FIG-20). Pictures take max-inline-size: 100% and block-size: auto (FIG-4). | TanreiFigure(title:caption:variant:isInset:separation:pattern:) { content } actions: { … } attachment: { … }, with titleContent: and captionContent: view builders for the two slots. The stage is a horizontal ScrollView only while its content is wider than it. SwiftUI has no figure trait: the view is an accessibility container (accessibilityElement(children: .contain)) whose label is the title, or the caption, or accessibilityLabel, with the caption as its hint where there is a title. The content's foreground is set with foregroundStyle in the outlined and filled looks. The ground pattern (FIG-26) is to be drawn with a Canvas behind the stage's content; not yet written. | TanreiFigure(title, caption, contentDescription, variant, inset, separation, pattern, actions = { … }, attachment = { … }) { content }, with titleContent and captionContent lambdas for the two slots. No clickable. The stage takes horizontalScroll only while its content is wider than it. A traversal group (semantics { isTraversalGroup = true }) with the name as its content description; Compose has no figure role. The content color is provided through LocalContentColor in the outlined and filled looks. The ground pattern (FIG-26) is to be drawn with Modifier.drawBehind on the stage; not yet written. | TanreiFigure(title:, caption:, semanticLabel:, variant:, inset:, separation:, pattern:, actions:, attachment:, child:), with titleWidget: and captionWidget: for the two slots. One Semantics(container: true, label:) around the parts, which stay in the tree. The stage is a horizontal SingleChildScrollView only while its child is wider than it. The content's default text and icon styles are set in the outlined and filled looks. The ground pattern (FIG-26) is to be a CustomPaint painter behind the stage's child; not yet written. | <Figure title="Variants" caption="…" actions={…} attachment={…}>…</Figure>; title and caption take a string or a node (the two slots). A View that is not itself accessible, so its children stay reachable, with accessibilityLabel on a wrapping group where the platform exposes one. The stage is a horizontal ScrollView only while its content is wider than it. Follows the app's direction where an ancestor's is not known. The content color is given through Tanrei's text context in the outlined and filled looks. pattern takes the same five values; the ground pattern (FIG-26) is to be drawn with an SVG pattern behind the stage's content; not yet written. |
Tokens
| Token | Alias de | Valor resuelto (claro) |
|---|---|---|
--tanrei-comp-figure-attachment-gap | sys.space.space100 | 8px |
--tanrei-comp-figure-caption-color | sys.color.on-surface-variant | |
--tanrei-comp-figure-caption-gap | sys.space.space100 | 8px |
--tanrei-comp-figure-container-shape | sys.shape.corner.medium | 8px |
--tanrei-comp-figure-content-color | sys.color.on-surface | |
--tanrei-comp-figure-divider-color | sys.color.outline-variant | |
--tanrei-comp-figure-divider-thickness | sys.border.hairline | 1px |
--tanrei-comp-figure-filled-container-color | sys.color.surface-container | |
--tanrei-comp-figure-header-gap | sys.space.space100 | 8px |
--tanrei-comp-figure-header-padding-block | sys.space.space100 | 8px |
--tanrei-comp-figure-header-padding-inline | sys.space.space200 | 16px |
--tanrei-comp-figure-header-padding-inline-end-with-actions | sys.space.space100 | 8px |
--tanrei-comp-figure-outline-color | sys.color.outline-variant | |
--tanrei-comp-figure-outline-width | sys.border.hairline | 1px |
--tanrei-comp-figure-outlined-container-color | sys.color.surface | |
--tanrei-comp-figure-pattern-checkerboard-size | sys.space.space100 | 8px |
--tanrei-comp-figure-pattern-clear-extent | — | 0.3 |
--tanrei-comp-figure-pattern-color | sys.color.surface-container-highest | |
--tanrei-comp-figure-pattern-dot-size | — | 3px |
--tanrei-comp-figure-pattern-line-thickness | sys.border.hairline | 1px |
--tanrei-comp-figure-pattern-spacing | sys.space.space300 | 24px |
--tanrei-comp-figure-plain-container-color | — | |
--tanrei-comp-figure-separation | sys.behavior.separation | 0 |
--tanrei-comp-figure-stage-padding-block | sys.space.space400 | 32px |
--tanrei-comp-figure-stage-padding-inline | sys.space.space300 | 24px |
--tanrei-comp-figure-title-color | sys.color.on-surface | |
--tanrei-comp-figure-caption-typescale | sys.typescale.body-small | 400 13px/1.5385 |
--tanrei-comp-figure-title-typescale | 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: outlined (27)
outlined
label: A specimen caption
caption: The medium corner, on a card. title
title: Variants title-caption
title: Revenue by quarter caption: Every region grew; the north grew fastes… title-slot
slots: title caption-slot
slots: caption actions
title: Variants slots: actions actions-only
label: A specimen slots: actions flush
caption: The harbour at low tide. inset: false title-flush
title: Harbour caption: The harbour at low tide. inset: false attachment
title: Variants slots: attachment separation-divider
title: Variants caption: A filled button and its markup. separation: divider slots: actions, attachment separation-gap
title: Variants caption: A filled button and its markup. separation: gap slots: actions, attachment long-caption
caption: Measured on the default system at standa… long-title-actions
title: Every variant of the button at each of i… slots: actions actions-rtl
title: الأشكال caption: زرّ ممتلئ وزرّ محدَّد. direction: rtl slots: actions ltr-title-rtl
title: tanrei-button v0.1 caption: comp.button.container.height.medium: 40p… direction: rtl attachment-rtl
title: الأشكال separation: divider direction: rtl slots: attachment pattern-grid
label: A specimen pattern: grid pattern-dots
label: A specimen pattern: dots pattern-grid-fade
label: A specimen pattern: grid-fade pattern-checkerboard
label: A specimen pattern: checkerboard title-pattern-grid-fade
title: Variants caption: A filled button and its markup. pattern: grid-fade slots: actions, attachment pattern-dots-rtl
title: الأشكال pattern: dots direction: rtl docs-demo
title: Variants, sizes and disabled pattern: grid-fade slots: actions docs-demo-code
title: Variants separation: divider pattern: grid-fade slots: actions, attachment docs-demo-system
title: Single choice, with glyphs, glyphs alone caption: Drawn under m3-like, a system that ships… pattern: grid-fade variant: filled (8)
filled
label: A specimen variant: filled filled-caption
caption: The medium corner, on a card. variant: filled filled-title-caption
title: Revenue by quarter caption: Every region grew; the north grew fastes… variant: filled filled-flush
caption: The harbour at low tide. variant: filled inset: false filled-attachment
caption: A filled button and its markup. variant: filled slots: attachment filled-separation-gap
title: Variants variant: filled separation: gap slots: attachment filled-pattern-grid
label: A specimen variant: filled pattern: grid filled-pattern-dots
label: A specimen variant: filled pattern: dots variant: plain (7)
plain
label: A specimen variant: plain plain-caption
caption: The medium corner, on a card. variant: plain plain-title-attachment
title: Variants caption: A filled button and its markup. variant: plain slots: attachment plain-caption-rtl
caption: الميناء عند الجزر. variant: plain direction: rtl plain-pattern-grid
caption: The plain look draws no pattern. variant: plain pattern: grid docs-specimen
caption: medium · 8px variant: plain docs-picture
caption: The review gallery, with one component's… variant: plain Generado a partir de specs/figure.spec.json, tokens/comp/figure.tokens.json, design/tokens/
variant |
Qué dibuja | Úsalo para |
|---|---|---|
outlined (predeterminado) |
La superficie dentro de una sola línea fina. | Una muestra, un ejemplo en vivo, un diagrama. |
filled |
Un tono discreto y ningún borde. | Una página que ya tiene muchas líneas; un fondo para cosas con sombra. |
plain |
Sin relleno, sin borde, sin margen interior y sin línea. | Una imagen que es su propio marco; una muestra en una cuadrícula. |
El aspecto outlined se rellena con el color de la superficie; no se deja vacío. Tus propios componentes conservan el contraste que se exigió a sus tokens, sea cual sea el panel en el que se coloque la figura.
title(el atributoheadlineen la web) es una línea corta en una cabecera situada dentro del marco. Da nombre a lo que se muestra.captionestá debajo del marco, en el borde de inicio, en texto secundario. Salta de línea y nunca se corta.- No hay ningún ajuste de posición. El texto que está encima del escenario es el título. Una leyenda tiene un único lugar.
- El título es texto sin más, no un encabezado. Donde el esquema de tu página necesite un encabezado ahí, escribe uno con
data-part="title": la figura lo dibuja con el estilo del título y conserva su rol y su nivel.
- Las acciones son tus propios controles al final de la cabecera: qué variante, qué tema, abrirlo en otro lugar. La figura los dispone en una fila y no hace nada más. Pasan debajo del título cuando la fila es demasiado estrecha.
- El bloque adjunto es tu propio bloque debajo del escenario, dentro del marco: el código a partir del cual se hizo un ejemplo, los datos de un gráfico.
separation |
Qué dibuja |
|---|---|
auto (predeterminado) |
Lo que eligió el sistema de diseño: líneas en el sistema predeterminado. |
divider |
Una línea debajo de la cabecera y otra encima del bloque adjunto, que queda a ras del marco. |
gap |
Ninguna línea. El bloque adjunto queda dentro del marco, retirado 8 de sus bordes, con su propia forma. |
inset(true de forma predeterminada) da al escenario un margen interior de 32 arriba y abajo y de 24 a los lados. En la web,flushquita el margen interior, de modo que una imagen, un gráfico o un mapa llegan hasta los bordes del marco y sus esquinas los recortan.- Una imagen se reduce conservando sus proporciones, y nunca se amplía.
- El contenido que no puede encogerse se desplaza hacia los lados dentro del escenario. La figura nunca es más ancha que su contenedor.
- El contenido más estrecho que un escenario con marco se centra. En el aspecto plain empieza en el borde del texto.
- El escenario es tan alto como su contenido. Cómo se disponen en él varios ejemplos es cosa de tu diseño de página.
pattern |
Qué dibuja | Para qué |
|---|---|---|
none (predeterminado) |
Solo el relleno del aspecto. | La mayoría de las figuras; una imagen que llena el escenario. |
grid |
Una línea fina cada 24, en horizontal y en vertical. | Un componente o una disposición mostrados sobre una cuadrícula. |
dots |
Un punto en cada cruce de esa cuadrícula. | Un dibujo o un diagrama, sobre un fondo más discreto. |
grid-fade |
La cuadrícula, despejada alrededor del centro y cada vez más marcada hacia las esquinas. | Un espécimen en el centro de un escenario grande. Los ejemplos en vivo de este sitio la usan. |
checkerboard |
Cuadrados de 8, alternando el relleno y el color del patrón. | Una imagen o un icono que puede ser transparente. |
- El patrón es decoración. Se dibuja detrás del contenido, en un único color discreto de la escala de superficies, y no se intensifica al subir el contraste.
- Se queda en su sitio mientras el contenido se desplaza en horizontal, y es igual en las dos direcciones.
- El aspecto plain no dibuja ninguno, porque no tiene un escenario donde dibujarlo. Los colores forzados lo quitan.
- No dibujes un patrón propio alrededor del escenario. Elige uno aquí, o cambia su estilo con los tokens
comp.figure.pattern.
- Una figura ocupa la anchura que se le da y no trae espacio exterior. En la prosa se espacia como un bloque y ocupa toda la anchura de la prosa, mientras que su leyenda se limita a la medida como un bloque de texto.
- Varias figuras una al lado de otra son una cuadrícula tuya. Una figura llena su celda.
- Escribe una leyenda que diga para qué está la figura: «Los ingresos crecieron en todas las regiones», no «Gráfico».
- Da a una imagen su propio texto alternativo. La leyenda no lo sustituye.
- Marca un ejemplo que hay que seguir o que hay que evitar con un tag pequeño al inicio de la leyenda, con su palabra: «Recomendado», «Evita».
- No uses una figura para agrupar contenido y acciones relacionados. Eso es una tarjeta.
- No hagas que una figura se pueda pulsar. Una imagen que abre algo es un enlace alrededor de la imagen.
- No des color al marco para decir que un ejemplo es correcto o incorrecto. La figura no tiene estado.
- Rol
figure- Etiquetado
- The figure is named by its title, or by its caption where it has no title, or by label where it draws neither. With both a title and a caption, the title is the name and the caption the description. A picture in the stage has its own text alternative, given by the product; the caption does not replace it. While the stage scrolls, it is a group with the figure's name, so that a person who reaches it by keyboard hears what scrolls.
- 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 | Moves through the product's controls in the header, then to the stage where it scrolls, then through what the stage, the attachment and the caption hold. The figure adds no stop of its own unless its stage scrolls. |
| ArrowLeft / ArrowRight / Home / End | While the scrolling stage has focus: scroll it sideways, as the platform scrolls a region. |
Notas
- Not interactive: the figure itself takes no press, so it has no target to size and minimumTarget holds trivially. The controls in its actions slot and anything operable in its stage are other components, each with its own target.
- A caption is not a text alternative. The caption says what the figure is for a reader who sees it ("Revenue grew in every region"); the picture's own alternative says what the picture shows to a reader who does not. Where the caption already says everything the picture does, the product marks the picture as decorative rather than repeat the caption.
- A live example in the stage stays fully operable and is read as what it is: the figure hides nothing from assistive technology and does not turn its content into an image. A purely decorative specimen (a swatch, a shape) is the product's to hide and to describe in the caption.
- A figure with neither a title nor a caption needs label; the component reports a figure without any name in debug builds (FIG-16) and cannot tell whether a name is a good one.
- A status such as do and don't is never given by a color on the frame: the figure has no status. A product that marks a figure as an example to follow or to avoid puts a tag with its glyph and its word at the start of the caption, where it is read as part of the figure's name or description.
- The scrolling stage is a focus stop (FIG-6) so that a keyboard user can bring every part of wide content into view (WCAG 2.1.1); it is named, and it shows the system's focus indicator, which is held at 3:1 against every surface role, the two fills of this component among them.
- Contrast in the default system: the title is on-surface on surface or surface-container and the caption is on-surface-variant on the surface the figure sits on, both role pairs held at 4.5:1 by the token invariants. The outlined look's edge and the dividers are decorative: the stage is told apart by its position and its caption, not by the line.
- The ground pattern (FIG-26) is decoration (WCAG 1.1.1): it is not exposed and carries nothing the content and the caption do not. It is drawn in surface-container-highest, a surface role against which on-surface text and the focus indicator are held by the token invariants, so text standing on a line or a dot keeps its contrast; and a raised contrast level does not make it louder. Forced colors remove it (FIG-20).
- Forced colors (FIG-20): the filled look loses its fill and gains an edge in the text color. The plain look stays unframed. No look draws a ground pattern.
Generado a partir de specs/figure.spec.json, tokens/sys/measure.tokens.json
- La figura nativa sigue siendo una figura. Recibe su nombre de su título, o de su leyenda donde no tiene título. Con ambos, el título es el nombre y la leyenda la descripción, y la leyenda se sigue leyendo en su lugar.
labelda nombre a una figura que no dibuja ninguno de los dos. Nunca se dibuja, y se ignora donde hay un título o una leyenda.- Mientras el escenario se desplaza hacia los lados, es una parada en el orden del foco, anterior a cualquier cosa que haya dentro de él, y un grupo con el nombre de la figura. Las teclas de flecha lo desplazan, e Inicio y Fin lo llevan a cada extremo. Un escenario que no se desplaza no añade ninguna parada.
- El anillo de foco se dibuja por dentro del borde del escenario, así que nada lo recorta.
- Todo lo que hay en la cabecera, el escenario, el bloque adjunto y la leyenda se puede seguir usando y conserva su orden de foco.
- Con el texto al 200%, el título y la leyenda crecen y saltan de línea, y las acciones pasan debajo del título.
- En un diseño de derecha a izquierda, la cabecera se refleja y la leyenda empieza a la derecha. Lo que se muestra en el escenario nunca se refleja.
- Con colores forzados, los aspectos outlined y filled tienen un borde del color del texto. El aspecto plain no tiene ninguno, y ningún aspecto dibuja un patrón.
- Las compilaciones de depuración notifican una figura sin nombre, una figura cuyo escenario está vacío y una variante, una separación o un patrón desconocidos.
- Da a cada figura un título, una leyenda o un
label. - Da a una imagen del escenario su propio
alt. Donde la leyenda ya diga todo lo que dice la imagen, marca la imagen como decorativa (alt=""). - Haz que un ejemplo en vivo se pueda seguir usando. La figura no oculta su contenido ni lo convierte en una imagen.