カード
関連するコンテンツのまとまりを背景から区切ります。カード全体を、中身を開く 1 つのアクションや、そこへ移動する 1 つのリンクにもできます。
- カテゴリ
- コンテインメント
- トークン
comp.card- レベル
- 基礎
- Web
tanrei-cardschedule - SwiftUI
TanreiCardschedule - Jetpack Compose
TanreiCardschedule - Flutter
TanreiCardschedule - React Native
Cardschedule
生成元 docs/status/status.json, specs/card.spec.json
バリアント
Outlined
売上は前四半期から 12% 伸びました。
Filled
売上は前四半期から 12% 伸びました。
Elevated
売上は前四半期から 12% 伸びました。
カードには 3 つの形があります。ふつうのカードはコンテナで、中身は自分のセマンティクスを保ち、ボタンやリンクを置けます。操作できるカードは 1 つのボタンです。リンクカード（href のあるカード）は 1 つのリンクです。押すと別のページやアドレスへ移動するならリンクカードを、その場で何かが起こるなら操作できるカードを使います。
Web と React の例は現在の仕様に沿っています。SwiftUI、Compose、Flutter、React Native は追従待ちで、ふつうのカードと操作できるカードは提供していますが、リンクカードはまだありません。これらの例は、いま提供しているものを示しています。
<!-- アクションではないカード。中身は自分のセマンティクスを保ち、ボタンを置くこともできます。 -->
<tanrei-card>
<h3 class="tanrei-text-heading-5">四半期レポート</h3>
<p class="tanrei-text-body">売上は前四半期から 12% 伸びました。</p>
<tanrei-button variant="text">共有</tanrei-button>
</tanrei-card>
<!-- 1 つのアクション。カード全体が label を名前とするボタンになります。中に操作できる要素は置きません。 -->
<tanrei-card variant="elevated" interactive label="四半期レポート">…</tanrei-card>
<!-- 1 つのリンク。href があると、カード全体が label を名前とするアンカーになります。中に操作できる要素は置きません。 -->
<tanrei-card href="/reports/q3/" label="四半期レポート">…</tanrei-card>
<!-- 新しいタブで開くリンクは、そのことを自分の言葉で伝えます。カードは印を描かないので、グリフは中身に置きます。 -->
<tanrei-card href="https://example.com/reports/q3.pdf" target="new" target-label="新しいタブで開きます" label="四半期レポート">
<h3 class="tanrei-text-heading-5">四半期レポート</h3>
<span class="tanrei-icon" aria-hidden="true">open_in_new</span>
</tanrei-card>
<!-- inset の既定値は true なので、属性は逆の意味の flush です。写真を端まで広げられます。 -->
<tanrei-card flush>
<img src="cover.jpg" alt="" />
<div style="padding: var(--tanrei-comp-card-container-padding)">…</div>
</tanrei-card>
<script type="module">
import '@tanrei/web/components/card';
document.querySelector('[interactive]').addEventListener('click', openReport);
// リンクカードは、ブラウザーがアドレスへ移動する前に click を発火します。クライアントサイドのルーターはこれをキャンセルします。
document.querySelector('tanrei-card[href]').addEventListener('click', (event) => {
event.preventDefault();
router.push(event.currentTarget.href);
});
</script>import { Card } from '@tanrei/react';
<Card variant="filled">
<h3 className="tanrei-text-heading-5">四半期レポート</h3>
<p className="tanrei-text-body">売上は前四半期から 12% 伸びました。</p>
</Card>
<Card interactive label="四半期レポート" onClick={openReport}>…</Card>
<Card href="/reports/q3/" label="四半期レポート">…</Card>
<Card href="https://example.com/reports/q3.pdf" target="new" targetLabel="新しいタブで開きます" label="四半期レポート">…</Card>
<Card inset={false}>…</Card>import Tanrei
TanreiCard(variant: .filled) {
Text("四半期レポート")
Text("売上は前四半期から 12% 伸びました。")
}
// action: を取るイニシャライザーが、操作できるカードです。
TanreiCard(label: Text("四半期レポート"), action: openReport) { ReportSummary() }
.disabled(isLoading)import io.github.chnotchy.tanrei.components.TanreiButton
import io.github.chnotchy.tanrei.components.TanreiCard
import io.github.chnotchy.tanrei.primitives.TanreiText
import io.github.chnotchy.tanrei.tokens.TanreiCardVariant
// onClick のないカードはアクションではないので、ボタンを置けます。
TanreiCard(variant = TanreiCardVariant.Filled) {
TanreiText("四半期レポート")
TanreiText("売上は前四半期から 12% 伸びました。")
TanreiButton(text = "共有", onClick = ::share)
}
// onClick を取るオーバーロードは 1 つのアクションです。enabled = false で無効になります。
TanreiCard(onClick = ::openReport, contentDescription = "四半期レポート") {
TanreiText("四半期レポート")
TanreiText("売上は前四半期から 12% 伸びました。")
}import 'package:tanrei/tanrei.dart';
TanreiCard(
variant: TanreiCardVariant.filled,
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: <Widget>[
const Text('四半期レポート'),
const Text('売上は前四半期から 12% 伸びました。'),
TanreiButton(onPressed: share, child: const Text('共有')),
],
),
);
// onTap が null でなければ、カード全体が 1 つのアクションになります。enabled: false で無効になります。
TanreiCard(
onTap: openReport,
semanticLabel: '四半期レポート',
child: const ReportSummary(),
);import { Text } from 'react-native';
import { Card, useContentColor } from '@tanrei/react-native';
// 文字列をそのまま渡すと、body のスタイルとカードのコンテンツ色で描かれます。
<Card variant="filled">売上は前四半期から 12% 伸びました。</Card>
// onPress を渡すと 1 つのアクションになります。名前には見出しのテキストを使います。
<Card accessibilityLabel="四半期レポート" onPress={openReport}>
<ReportSummary />
</Card>
// React Native には文字色の継承がないため、自前のテキストはカードのコンテンツ色を読み取ります。
function ReportSummary() {
const color = useContentColor();
return <Text style={{ color }}>売上は前四半期から 12% 伸びました。</Text>;
}端まで広げる、操作できる、無効
flush：中身が端まで届きます。
四半期レポート
操作できるカード。ホバー、Tab でのフォーカス、押下を試せます。
四半期レポート
操作できるカードの無効状態。
リンクカード
ボタン
リンクカード。Enter で移動でき、ブラウザーのリンクのメニューも使えます。
リスト
新しいタブで開きます。グリフは中身の一部です。
ボタン
無効なリンクカード。移動できません。
構成要素
構成要素
outlined の上に描いています。| パーツ | 説明 |
|---|---|
1 container | The shape that holds the content, clips it to its corners and, for an interactive card, carries hover, focus and press. |
2 outline · 任意 | The border of the outlined variant. |
3 content | Whatever the product puts in the card. The card does not lay it out; it only insets it, clips it and hands it a content color. |
4 focus-ring · 任意 | Gap-then-ring indicator shown for keyboard focus of an interactive card. |
プロパティ
| プロパティ | 型 | 既定値 | 説明 |
|---|---|---|---|
variant | elevated | filled | outlined | "outlined" | How the card separates from its background: by depth (elevated), by tone (filled) or by an edge (outlined). Pick by the background, not by importance. A design system may add values. |
interactive | boolean | false | Makes the whole card one pressable action (it emits click). Its content must then contain no other interactive element. A card whose action is to go somewhere takes href instead and is a link, not a button. |
disabled | boolean | false | Prevents interaction and removes an interactive card or a link card from the focus order. Ignored unless interactive is true or href is set: a card that is neither an action nor a link cannot be disabled. |
href | string | "" | The destination: an address as the platform's links take one (a URL; on the web a path or a fragment as well). Not empty, it makes the whole card one link — a link card — whether interactive is set or not: the link role, one tab stop, activated by pointer, touch or Enter and not by Space, opened by the platform as its own links are, and drawn exactly as an interactive card is (CRD-19, CRD-20). Its content must then contain no other interactive element, as an interactive card's. |
target | same | new | "same" | Where the destination opens. same: where the person is — the same tab on the web, the app's own handling of the address elsewhere. new: a new context — a new tab or window on the web, outside the current screen elsewhere — which the card says through targetLabel; the card draws no mark, because its content is the product's (CRD-21). Ignored without href. |
targetLabel | string | "" | What assistive technology reads after the link's name while target is new ("opens in a new tab"). Tanrei ships no words of its own, so the product gives them in its own language, as it gives a chip its removeLabel. Required while target is new; ignored otherwise. |
inset | boolean | true | Insets the content by the card's padding. Set it to false for content that reaches the card's edges (a photo on top); that content pads its own text. |
label | string | "" | The accessible name. For an interactive card or a link card, normally the text of its heading; without it the whole content becomes the name. For a card that is neither, a label makes it a named group. |
スロット
| スロット | 説明 |
|---|---|
default | The content: any layout of media, text and — only when interactive is false and href is empty — actions. |
イベント
| イベント | 説明 |
|---|---|
click | An interactive card or a link card was activated by pointer, touch, keyboard or assistive technology. A link card emits it before its destination opens; a product that takes the navigation itself (a client-side router) cancels it (CRD-20). |
状態
振る舞い
EARS 記法による要件です。各プラットフォームの実装は、この ID に対応するテストで検証されます。要件の原文は仕様ファイルのものをそのまま掲載しています。
| ID | 要件 |
|---|---|
CRD-1 | WHEN the user activates an interactive card by pointer, touch, Enter or Space — a link card (CRD-19) by pointer, touch or Enter — THE card SHALL emit click exactly once. |
CRD-2 | WHILE disabled is true and either interactive is true or href is not empty THE card SHALL NOT emit click, SHALL NOT be focusable and SHALL expose the disabled state to assistive technology. |
CRD-3 | WHILE an interactive card is hovered, keyboard-focused or pressed THE card SHALL render its container, outline, elevation, content color and opacity from the component tokens of the highest-precedence active state, with precedence pressed over focused over hovered; focus gained by pointer or touch SHALL NOT select the focused state. |
CRD-4 | WHEN an interactive card receives keyboard focus THE card SHALL show the focus ring without animation; focus gained by pointer or touch SHALL NOT show it. |
CRD-5 | WHERE the visual size of an interactive card is below the minimum target THE card SHALL extend its hit area on both axes to sys.target.touch for touch input and sys.target.pointer for fine pointers, without changing its visual size; a platform that cannot tell the input type SHALL use sys.target.touch. |
CRD-6 | WHILE disabled is true and either interactive is true or href is not empty THE card SHALL render its container, outline, elevation, content color and opacity from the disabled component tokens of its variant. |
CRD-7 | WHEN variant names a value that the active design system does not have THE card SHALL render with the default value's tokens, and in debug builds report the unknown value. |
CRD-8 | WHEN the card is pressed by pointer, touch, Enter or Space THE card SHALL show the pressed state without delay and SHALL keep it visible for at least sys.motion.duration.press-hold, even when the press ends sooner. A press — held, or moved with the pointer down — SHALL NOT select the card's text nor start a drag of it: the card is one action, as a button is, and the platform keeps a button's text from selection. |
CRD-9 | WHILE pressed THE card SHALL answer as sys.behavior.pressed-feedback names: overlay applies the pressed tokens to the whole container at once; ripple grows the pressed state layer from the point of contact (from the center for keyboard activation); dim applies the pressed opacity to the whole control and draws no state layer; none draws no answer to the press. Under ripple and dim only the container color stays with the state under the press; content color, outline, elevation, opacity and shape still come from the pressed tokens. Under none every part stays with the state under the press. The ripple grows over comp.card.motion.feedback-duration with comp.card.motion.state-easing, fades over comp.card.motion.state-duration with comp.card.motion.state-easing once the press has ended and press-hold has passed, and appears whole where motion is reduced. |
CRD-10 | THE card 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) and show its keyboard focus as sys.behavior.focus-style names (ring or glow); a platform that cannot draw a choice SHALL fall back to the first value and state that in its README. |
CRD-11 | WHILE interactive is false and href is empty THE card SHALL NOT be focusable, SHALL NOT emit click, SHALL NOT draw a hover, focus or press answer, SHALL ignore disabled, and SHALL render from the resting tokens of its variant. |
CRD-12 | WHILE inset is true THE card SHALL place its content comp.card.container.padding inside the container on every side; WHILE inset is false the content SHALL reach the container's edges. In both cases THE card SHALL clip its content to the container's shape, draw the outline of the outlined variant (comp.card.outline.width wide) above the content, and grow with its content: the card has no height of its own. |
CRD-13 | THE card SHALL hand its content the content color of its variant and state (comp.card.outlined.content.color for outlined at rest, and so on) as the platform's inherited foreground (the web's inherited color, SwiftUI's foreground style, Compose's content color, Flutter's default text and icon style); on React Native, which has no inherited text color, it SHALL provide the color through the Tanrei context that Tanrei's text components read. Plain text given as content, where the platform must style it, SHALL take sys.typescale.body. |
CRD-14 | WHILE interactive is true THE card SHALL be exactly one focusable element with the button role (the link role WHILE href is not empty, CRD-19), named by label, over a name the product gives it on the element (aria-label or aria-labelledby), or, WHILE label is empty, by the name the product gives it on the element — aria-label, or aria-labelledby naming an element — or else by the text of its content merged in reading order, and in debug builds SHALL report, WHILE it has neither label nor a name of the product's, that it has no label; WHILE interactive is false and href is empty THE card SHALL have no role of its own and leave its content's semantics untouched, except that WHERE label is set it SHALL be a group named by label. |
CRD-15 | WHILE interactive is true or href is not empty THE card's content SHALL contain no interactive element (button, link, field, toggle or anything else focusable); a platform that can inspect its content (the web, on every slot change) SHALL report one in debug builds, and a platform that cannot SHALL state the rule in its README and docs page. |
CRD-16 | WHEN the elevation or the colors of an interactive card change between states THE card SHALL animate the change over comp.card.motion.state-duration with comp.card.motion.state-easing, and SHALL change them at once where motion is reduced. |
CRD-17 | WHEN the layout direction is right-to-left THE card SHALL apply its padding and clipping by logical start and end so that it mirrors, SHALL grow a ripple from the point of contact as in left-to-right, and SHALL NOT mirror its content itself: the content follows the layout direction. |
CRD-18 | THE card 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 card is shown THE card SHALL draw itself for the new direction at once, without a motion of its own, keeping what it shows and its state. |
CRD-19 | WHILE href is not empty THE card SHALL be a link card, whether interactive is true or false: exactly one focusable element with the link role and not the button role, named as CRD-14 names an interactive card, its content presentational and held to CRD-15; the platform's own link to href (the web's anchor element; SwiftUI's Link; on Compose, Flutter and React Native an element with the platform's link semantics whose address is opened by the platform's opener), so that whatever the platform gives a link — on the web its context menu, opening in a new tab or window, copying and dragging its address, and the address shown before it is followed — is the platform's, and not the card's to draw or to take over; and everything this spec says of an interactive card other than its role and its keys — its states, focus ring, minimum target, press answer, corners, motion and disabled look (CRD-3 to CRD-6, CRD-8 to CRD-10, CRD-16) — SHALL hold for a link card from the same tokens, with no look of its own for a link and none for a destination already visited. |
CRD-20 | WHEN the user activates a link card by pointer, touch or Enter THE card SHALL emit click exactly once and then open href where target names, unless the product cancelled that click, in which case it SHALL open nothing: the product's own router has taken the navigation. It SHALL show the pressed state as CRD-8 and CRD-9 say and SHALL NOT hold the navigation back for sys.motion.duration.press-hold. THE card SHALL NOT activate a link card on Space, which on the web scrolls the page as it does on any link, and SHALL NOT show the pressed state for it; WHERE the platform gives its links other keys or gestures (on the web a modified or a middle click that opens a new tab, on Apple platforms a long press that previews) THE card SHALL leave them to the platform. |
CRD-21 | WHILE the card is a link card and target is new THE card SHALL open href in a new context — on the web a new tab or window that is given no handle to the page that opened it; on the other platforms outside the screen the person is on, as the platform's opener decides. THE card SHALL draw no mark of its own for it, because its content is the product's to lay out (CRD-12): a product that shows that the card opens elsewhere puts the glyph open_in_new of the system's icon set in the content, through the icon helper. WHILE target is new THE card SHALL expose targetLabel as its description, read after its name and role, and WHILE targetLabel is empty SHALL still render and in debug builds report that a link that opens a new context does not say so. WHILE target is same THE card SHALL ignore targetLabel. |
CRD-22 | WHILE href is not empty and disabled is true THE card SHALL NOT be a link that can be followed: it SHALL render as CRD-6 says, SHALL expose the link role with the disabled state and no destination, SHALL NOT be focusable, SHALL NOT emit click, and SHALL open nothing by any means the platform gives a link (on the web the anchor carries no href, so there is no context menu entry, no drag and no new tab for it). |
CRD-23 | WHEN target names a value the card does not define THE card SHALL behave as same, and in debug builds report the unknown value. IF href is only white space, or names a script to run rather than a place to go (the web's javascript: scheme), or cannot be read as an address by the platform, THE card SHALL be the card its interactive makes it, without a destination, and in the last two cases report it in debug builds. |
CRD-24 | WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE card SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on the element that carries its role — an id reference by the elements it names in the host's tree or a tree around it, an error message as part of the description while the card is invalid — except those the card owns (aria-disabled), which it SHALL move and not expose. WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE card SHALL take it off that element. WHEN the product sets an aria- attribute the card owns THE card SHALL report it in debug builds. |
プラットフォーム別の名前対応
パリティは API が同一であることを意味しません。同じ契約を、各プラットフォームの流儀で表現します。
| 仕様 | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
|---|---|---|---|---|---|
| コンポーネント | tanrei-card | TanreiCard | TanreiCard | TanreiCard | Card |
variant · プロパティ | variant | variant | variant | variant | variant |
interactive · プロパティ | interactive | action | onClick | onTap | onPress |
disabled · プロパティ | disabled | disabled | enabled | enabled | disabled |
href · プロパティ | href | destination | href | href | href |
target · プロパティ | target | target | target | target | target |
targetLabel · プロパティ | targetLabel | targetLabel | targetLabel | targetSemanticLabel | targetLabel |
inset · プロパティ | inset | inset | inset | inset | inset |
label · プロパティ | label | label | contentDescription | semanticLabel | accessibilityLabel |
click · イベント | click | action | onClick | onTap | onPress |
| 備考 | The content is the default slot. inset is a boolean property that defaults to true; its attribute is the inverse flush, because an HTML boolean attribute cannot default to true. click fires only while interactive is true and disabled is false. With href the shadow root holds an <a part="container"> around the slot in place of the element with role button; click then fires for a link card too. The link form: href is the href attribute; target is the target attribute with the values same and new (the HTML spellings _self and _blank are read as those two; anything else is same and reported); targetLabel is the target-label attribute. Web-only, forwarded to the anchor and to nothing else: rel (to which new adds noopener) and download. Cancelling click (preventDefault()) cancels the navigation, which is how a client-side router takes it; a modified or a middle click is the browser's. A disabled link is the anchor without href, with role="link" and aria-disabled="true", as the navigation drawer's destination already is. Space is not handed to the press controller. element.click() follows the link. | SwiftUI idiom (as Button): the initializer that takes action: makes the card interactive; the one without it is a plain container. disabled follows .disabled(_:); label sets accessibilityLabel. Content is a @ViewBuilder. Not built on this platform yet: the initializer that takes destination: URL in place of action: draws the same control as a SwiftUI Link, so the address is opened by the environment's openURL — an app that routes addresses itself provides an OpenURLAction, which is how the navigation is cancelled — and VoiceOver reads the link trait. target: TanreiLinkTarget = .same and targetLabel (the accessibility hint) are parameters of that initializer alone. | Compose idiom (as Card): the overload with a non-null onClick is interactive; enabled is the inverse flag. Content is a ColumnScope lambda and reads the content color from LocalTanreiContentColor and plain text's style from LocalTanreiTextStyle, Tanrei's own locals (the package does not depend on Material, whose LocalContentColor it would otherwise be). Not built on this platform yet: the overload that takes href: String (onClick is then optional and called first) opens the address through LocalUriHandler.current after onClick; an app that routes addresses itself provides its own UriHandler. Compose has no link role for a clickable element (only link annotations inside text), so the node drops Role.Button and carries no role, and the README says so. target: TanreiLinkTarget = TanreiLinkTarget.Same; targetLabel is appended to the node's state description. | Flutter idiom: a non-null onTap makes the card interactive. enabled: false disables it while keeping its interactive look (as ListTile), because a null onTap already means not interactive. Content is child. Not built on this platform yet: the TanreiCard.link constructor (href is a Uri) has Semantics(link: true) with the address as its linkUrl. The package has no plugin dependency, so the address is opened by the nearest TanreiLinkOpener, an inherited widget the app provides once (calling url_launcher, or its own router); without one the control opens nothing and reports it in debug builds. target is a TanreiLinkTarget; targetSemanticLabel is the semantics hint. | A non-null onPress makes the card interactive (an accessible Pressable with the button role); without it the card is a View. Content is children. Not built on this platform yet: a Card with href has accessibilityRole="link" and opens the address with Linking.openURL after onPress, unless onPress called event.preventDefault(). target is "same" | "new"; targetLabel is the accessibilityHint. |
トークン
| トークン | 参照先 | 解決値（ライト） |
|---|---|---|
--tanrei-comp-card-container-padding | sys.space.space200 | 16px |
--tanrei-comp-card-container-shape | sys.shape.corner.medium | 8px |
--tanrei-comp-card-disabled-opacity | — | 0.38 |
--tanrei-comp-card-elevated-container-color | sys.color.surface-container-lowest | |
--tanrei-comp-card-elevated-container-elevation | sys.elevation.level2 | 0px 0px 0px 1px rgb(0 0 0 / 0.08), 0px 1px 2px 0px rgb(0 0 0 / 0.04) |
--tanrei-comp-card-elevated-content-color | sys.color.on-surface | |
--tanrei-comp-card-elevated-disabled-container-color | — | |
--tanrei-comp-card-elevated-disabled-container-elevation | — | 0px 0px 0px 1px rgb(0 0 0 / 0.08) |
--tanrei-comp-card-elevated-disabled-content-color | — | |
--tanrei-comp-card-elevated-disabled-outline-color | — | |
--tanrei-comp-card-elevated-disabled-state-layer-color | — | |
--tanrei-comp-card-elevated-focused-container-color | — | |
--tanrei-comp-card-elevated-focused-container-elevation | — | 0px 0px 0px 1px rgb(0 0 0 / 0.08), 0px 1px 2px 0px rgb(0 0 0 / 0.04) |
--tanrei-comp-card-elevated-focused-content-color | — | |
--tanrei-comp-card-elevated-focused-outline-color | — | |
--tanrei-comp-card-elevated-focused-state-layer-color | — | |
--tanrei-comp-card-elevated-hovered-container-color | — | |
--tanrei-comp-card-elevated-hovered-container-elevation | — | 0px 0px 0px 1px rgb(0 0 0 / 0.08), 0px 1px 1px 0px rgb(0 0 0 / 0.04), 0px 4px 8px -4px rgb(0 0 0 / 0.04), 0px 16px 24px -8px rgb(0 0 0 / 0.06) |
--tanrei-comp-card-elevated-hovered-content-color | — | |
--tanrei-comp-card-elevated-hovered-outline-color | — | |
--tanrei-comp-card-elevated-hovered-state-layer-color | — | |
--tanrei-comp-card-elevated-outline-color | — | |
--tanrei-comp-card-elevated-pressed-container-color | — | |
--tanrei-comp-card-elevated-pressed-container-elevation | — | 0px 0px 0px 1px rgb(0 0 0 / 0.08), 0px 1px 2px 0px rgb(0 0 0 / 0.04) |
--tanrei-comp-card-elevated-pressed-content-color | — | |
--tanrei-comp-card-elevated-pressed-outline-color | — | |
--tanrei-comp-card-elevated-pressed-state-layer-color | — | |
--tanrei-comp-card-elevated-state-layer-color | comp.card.elevated.content.color | |
--tanrei-comp-card-filled-container-color | sys.color.surface-container-highest | |
--tanrei-comp-card-filled-container-elevation | sys.elevation.level0 | |
--tanrei-comp-card-filled-content-color | sys.color.on-surface | |
--tanrei-comp-card-filled-disabled-container-color | — | |
--tanrei-comp-card-filled-disabled-container-elevation | — | |
--tanrei-comp-card-filled-disabled-content-color | — | |
--tanrei-comp-card-filled-disabled-outline-color | — | |
--tanrei-comp-card-filled-disabled-state-layer-color | — | |
--tanrei-comp-card-filled-focused-container-color | — | |
--tanrei-comp-card-filled-focused-container-elevation | — | |
--tanrei-comp-card-filled-focused-content-color | — | |
--tanrei-comp-card-filled-focused-outline-color | — | |
--tanrei-comp-card-filled-focused-state-layer-color | — | |
--tanrei-comp-card-filled-hovered-container-color | — | |
--tanrei-comp-card-filled-hovered-container-elevation | — | |
--tanrei-comp-card-filled-hovered-content-color | — | |
--tanrei-comp-card-filled-hovered-outline-color | — | |
--tanrei-comp-card-filled-hovered-state-layer-color | — | |
--tanrei-comp-card-filled-outline-color | — | |
--tanrei-comp-card-filled-pressed-container-color | — | |
--tanrei-comp-card-filled-pressed-container-elevation | — | |
--tanrei-comp-card-filled-pressed-content-color | — | |
--tanrei-comp-card-filled-pressed-outline-color | — | |
--tanrei-comp-card-filled-pressed-state-layer-color | — | |
--tanrei-comp-card-filled-state-layer-color | comp.card.filled.content.color | |
--tanrei-comp-card-focused-opacity | — | 1 |
--tanrei-comp-card-hovered-opacity | — | 1 |
--tanrei-comp-card-motion-feedback-duration | sys.motion.role.feedback | 450ms |
--tanrei-comp-card-motion-state-duration | sys.motion.role.state.large | 250ms |
--tanrei-comp-card-motion-state-easing | sys.motion.easing.state | cubic-bezier(0.2, 0, 0, 1) |
--tanrei-comp-card-outline-width | sys.border.hairline | 1px |
--tanrei-comp-card-outlined-container-color | sys.color.surface | |
--tanrei-comp-card-outlined-container-elevation | sys.elevation.level0 | |
--tanrei-comp-card-outlined-content-color | sys.color.on-surface | |
--tanrei-comp-card-outlined-disabled-container-color | — | |
--tanrei-comp-card-outlined-disabled-container-elevation | — | |
--tanrei-comp-card-outlined-disabled-content-color | — | |
--tanrei-comp-card-outlined-disabled-outline-color | — | |
--tanrei-comp-card-outlined-disabled-state-layer-color | — | |
--tanrei-comp-card-outlined-focused-container-color | — | |
--tanrei-comp-card-outlined-focused-container-elevation | — | |
--tanrei-comp-card-outlined-focused-content-color | — | |
--tanrei-comp-card-outlined-focused-outline-color | — | |
--tanrei-comp-card-outlined-focused-state-layer-color | — | |
--tanrei-comp-card-outlined-hovered-container-color | — | |
--tanrei-comp-card-outlined-hovered-container-elevation | — | |
--tanrei-comp-card-outlined-hovered-content-color | — | |
--tanrei-comp-card-outlined-hovered-outline-color | — | |
--tanrei-comp-card-outlined-hovered-state-layer-color | — | |
--tanrei-comp-card-outlined-outline-color | sys.color.outline-variant | |
--tanrei-comp-card-outlined-pressed-container-color | — | |
--tanrei-comp-card-outlined-pressed-container-elevation | — | |
--tanrei-comp-card-outlined-pressed-content-color | — | |
--tanrei-comp-card-outlined-pressed-outline-color | — | |
--tanrei-comp-card-outlined-pressed-state-layer-color | — | |
--tanrei-comp-card-outlined-state-layer-color | comp.card.outlined.content.color | |
--tanrei-comp-card-pressed-opacity | — | 1 |
フィクスチャ
基準となる描画パターンです。全プラットフォームが同じ ID でスナップショットを撮り、結果を比較できるようにしています。
variant: elevated (2)
elevated
variant: elevated elevated-disabled
variant: elevated interactive: true disabled: true label: Quarterly report variant: filled (2)
filled
variant: filled filled-link-new
variant: filled href: https://example.com/tanrei target: new targetLabel: opens in a new tab label: Source variant: outlined (6)
outlined
variant: outlined outlined-flush
variant: outlined inset: false outlined-interactive
variant: outlined interactive: true label: Quarterly report outlined-disabled
variant: outlined interactive: true disabled: true label: Quarterly report outlined-link
variant: outlined href: /getting-started/ label: Getting started outlined-link-disabled
variant: outlined disabled: true href: /getting-started/ label: Getting started 生成元 specs/card.spec.json, tokens/comp/card.tokens.json, design/tokens/
レポート、人物、商品、設定項目など、1 つの対象についての情報をまとめ、周りから区切りたいときに使います。カードがするのは、中身に余白を取り、角で切り抜き、色を渡すことだけです。中身のレイアウトは、Tanrei のテキストスタイル（カードのタイトルには heading-5）やコンポーネントを使って組み立てます。
カードが「中身を開く」という 1 つのアクションなら、カード全体を操作できるようにします。アクションが複数あるなら、カードは操作できないままにして、中にボタンを置きます。
移動先のあるコントロールはリンクです。カードも同じです。押すと別のページへ移動するだけなら、操作できるカードの click で移動させるのではなく、href を指定します。カードは本物のリンクになり、Web では中身を包むアンカーになります。新しいタブで開く、アドレスをコピーする、移動する前に行き先を確かめる、といったことができ、支援技術はボタンではなくリンクとして読み上げます。このサイトでページからページへ案内しているカードも、リンクカードです。
- リンクカードの見た目は、どの状態でも操作できるカードとまったく同じです。リンク専用の見た目も、訪問済みの状態もありません。
hrefはinteractiveより優先されます。両方を指定したカードはリンクです。- リンクカードは Enter で移動します。Space では移動しません。Space はふつうのリンクと同じ働きをし、Web ではページをスクロールします。
- 先に
clickが発火し、そのあとで移動先が開きます。クライアントサイドのルーターのように移動を自分で扱うなら、その click をキャンセルします。 targetはsame（既定）かnewです。新しいタブやウィンドウで開くリンクにはtargetLabelが必要です。名前のあとに読まれる言葉で、「新しいタブで開きます」などと書きます。Tanrei は言葉を同梱しません。中身は利用者側のものなので、カードは印を描きません。示したい場合は、中身にopen_in_newのグリフを置きます。- 無効なリンクカードは、どの方法でも移動できず、フォーカスの順序からも外れます。
- 空白だけの
hrefは移動先になりません。javascript:のアドレスや、アドレスとして読めない値は受け付けず、デバッグビルドで報告します。カードはhrefがないときと同じになります。
移動先と独自のアクションの両方が必要なカードは、ふつうのカードのままにして、見出しをリンクにするか、href を指定したボタンを中に置きます。
重要度ではなく、置く背景で選びます。
| バリアント | 区切り方 | 用途 |
|---|---|---|
| Outlined（既定） | 輪郭線 | ほとんどのカード。Filled のカードと同じ色調のサーフェスに置くとき。 |
| Filled | 色調 | 無地のサーフェスの上で、色調の違いだけでまとまりを示せるとき。同じ色調のサーフェスに置くと見えなくなります。 |
| Elevated | 奥行き | ピン留めした項目やドラッグできる項目など、ページより手前にあるもの。 |
- 操作できるカードとリンクカードには
labelで名前を付けます。ふつうは見出しのテキストです。 - 一緒に並べるカードは、バリアントをそろえます。
- 端まで広げたい画像には
insetを false（Web ではflush）にし、その下のテキストにはカードの余白トークンで自分で余白を取ります。
- 操作できるカードやリンクカードの中に、ボタン、リンク、入力欄、トグルなど、フォーカスを受ける要素を置かない。支援技術から届かず、押すとカードまで反応します。
- 操作できるカードの click ハンドラーからページを移動しない。移動するカードには
hrefを指定します。 - ふつうのカードを無効にしない。無効にするアクションもリンクもないので、
disabledは無視されます。 - カードの重要度を奥行きで表さない。
- ロール
button (link while href is set)- ラベル付け
- The role is button while interactive is true and link while href is set; otherwise the card has no role, or is a group when label is set. An interactive card's or a link card's name is label — normally its heading's text — or, without one, its whole content read as one string (reported in debug builds). Their content is presentational: its headings and images are read as part of the name, not as separate elements. While target is new, targetLabel is a link card's description.
- 最小ターゲット
- 見た目のサイズが小さくても、ヒット領域は最小ターゲットサイズを満たします。 minimum 32px · pointer 44px · spacing 8px · touch 48px
キーボード操作
| キー | 動作 |
|---|---|
| Tab | Moves focus to an interactive card or a link card. A card that is neither is not a tab stop; focus moves through its content. |
| Enter / Space | Activates an interactive card. A link card is activated by Enter alone: Space does what it does on any link (on the web it scrolls the page). |
備考
- Never nest interactive elements in an interactive card or a link card: assistive technology cannot reach them (the card is one element) and a press on them would also activate the card. A card that needs its own buttons or links stays plain, and its primary action or destination is one of them: a heading that is a link, or a link Button.
- Web: an interactive card draws a shadow element with role button and tabindex 0 around the slot (not a <button>, whose content model forbids block content); Enter activates on keydown and Space on keyup, as a native button does. A link card draws an anchor around the slot instead, which HTML allows around block content that holds nothing interactive. In debug builds either inspects the slotted content on every slotchange for focusable or interactive descendants and reports them.
- SwiftUI, Compose, Flutter and React Native merge the content into the one accessible element (SwiftUI's button, Compose's merged clickable semantics, Flutter's merged semantics, React Native's accessible Pressable). None of them can reliably detect a nested interactive element, so each states the rule in its README; their tests assert that the merged element is the only one exposed.
- Text size does not clip a card: it grows with its content at 200% text size.
- How a state looks is a value decision of the active design system; components read the state's tokens and never compute the effect themselves.
- A card with a destination is a link: one element with the link role, the platform's own link, Enter and not Space, so that on the web the card can be opened in a new tab and its address copied. No visited state is drawn.
- A link card that opens a new context says so through targetLabel. The card draws no mark of its own, since it does not lay out its content; a product that shows one puts the glyph open_in_new of the system's icon set in the content, where the icon helper mirrors it in a right-to-left layout.
生成元 specs/card.spec.json, tokens/sys/measure.tokens.json
- 操作できないカードはロールを持たず、中身のセマンティクスに手を加えません。
labelがあれば、それを名前とするグループになります。 - 操作できるカードは、ボタンのロールを持つフォーカス可能な 1 つの要素になり、無効状態も伝えます。名前は
labelです。ない場合は中身全体が 1 つの文字列として読まれ、デバッグビルドで報告されます。 - リンクカードは、リンクのロールを持つフォーカス可能な 1 つの要素になり、名前の決まり方は同じです。
targetがnewのあいだは、targetLabelが説明として、名前とロールのあとに読まれます。無効なリンクカードはリンクのロールのまま無効状態を伝え、移動先を持ちません。 - 操作できるカードは Enter と Space で、リンクカードは Enter だけで実行します。ヒット領域は最小ターゲットを満たし、フォーカスインジケーターはキーボードフォーカスのときだけ表示します。
- 中身に合わせて伸びるので、文字を大きくしても切れません。
- Web では、操作できるカードやリンクカードの中に操作できる要素があると、スロットが変わるたびにデバッグビルドで報告します。新しいタブで開くリンクカードに
targetLabelがない場合も報告します。
プラットフォームごとの既知の制約：
- SwiftUI、Compose、Flutter、React Native には、まだリンクカードがありません。これらでは、移動するカードも、アクションの中で移動する操作できるカードのままです。
- Web：カードに入れた要素の内側へ、後から操作できる要素を加えた場合は報告されません。
- Web：操作できないカードが自分から click を出すことはありませんが、中身をクリックすると通常の DOM の click が発生し、カードを通ってバブリングします。
- SwiftUI、Compose、Flutter、React Native は、入れ子になった操作できる要素を検出できないため、確認しません。このルールは利用者側で守ってください。
- React Native では、
labelのある操作できないカードは group のロールになりますが、iOS はこのロールをどのトレイトにも対応付けません。VoiceOver がグループの名前を読み上げるかは、実機でまだ確かめていません。 - Compose：プラットフォームのキー処理を通した Enter と Space での実行は Robolectric 上でしか確かめておらず、実機ではまだ試していません。
- React Native には文字色の継承がありません。文字列はカードがコンテンツ色で描きますが、自前のテキストは
useContentColor()で色を読み取ります。 - SwiftUI：最小ターゲットより小さい操作できるカードは、見た目の大きさはそのままで、レイアウト上はターゲットの大きさを占めます。
- 操作できるカードとリンクカードには
labelを付けます。付けないと、中身全体が長い 1 つの名前として読まれます。 - 新しいタブやウィンドウで開くリンクカードには、プロダクトの言語で
targetLabelを付けます。 - 操作できるカードとリンクカードに、ほかのコントロールを入れないでください。ボタンやリンクが必要なカードはふつうのカードにして、そのうちの 1 つを主なアクションや移動先にします。
- 操作できないカードの中身には、代替テキストや見出しレベルなど、それぞれにセマンティクスを付けます。カードは何も補いません。