メーター
ストレージの使用量、電池の残量、割り当ての消費、パスワードの強さのように、決まった範囲の中で、ある値がどこにあるかを示します。見た目はプログレスインジケーターと同じバーまたはリングですが、何かが進行中だとは伝えません。
- カテゴリ
- コミュニケーション
- トークン
comp.meter- レベル
- 基礎
- Web
tanrei-meterclock_loader_40 - SwiftUI
TanreiMeterradio_button_unchecked - Jetpack Compose
TanreiMeterradio_button_unchecked - Flutter
TanreiMeterradio_button_unchecked - React Native
Meterradio_button_unchecked
生成元 docs/status/status.json, specs/meter.spec.json
リニアとサーキュラー
Web と React の例は現在の仕様に沿っています。SwiftUI、Compose、Flutter、React Native は予定で、まだメーターを提供していません。
<tanrei-meter value="0.62" label="ストレージの使用量" value-text="15 GB 中 9.3 GB"></tanrei-meter>
<tanrei-meter value="37" max="50" label="予約済みの席" value-text="50 席中 37 席"></tanrei-meter>
<!-- 値が何を意味するかはプロダクトが決め、言葉でも伝えます。 -->
<tanrei-meter value="0.85" status="warning" label="ストレージの使用量" value-text="残りわずか：15 GB 中 12.8 GB"></tanrei-meter>
<tanrei-meter variant="circular" size="small" value="0.62" label="バッテリー"></tanrei-meter>
<script type="module">
import '@tanrei/web/components/meter';
const meter = document.querySelector('tanrei-meter');
meter.value = used / quota;
meter.status = used / quota > 0.8 ? 'warning' : 'default';
</script>import { Meter } from '@tanrei/react';
<Meter value={used / quota} label="ストレージの使用量" valueText={`${quotaText} 中 ${usedText}`} />
<Meter value={seats} max={50} label="予約済みの席" valueText={`50 席中 ${seats} 席`} />
<Meter
value={used / quota}
status={used / quota > 0.8 ? 'warning' : 'default'}
label="ストレージの使用量"
valueText={used / quota > 0.8 ? `残りわずか：${quotaText} 中 ${usedText}` : `${quotaText} 中 ${usedText}`}
/>
<Meter variant="circular" size="small" value={charge} label="バッテリー" />ステータス：default、info、success、warning、error
サイズ、範囲の両端、独自の範囲
区切り方：divider（既定のシステムの選択）と gap
構成要素
構成要素
linear の上に描いています。| パーツ | 説明 |
|---|---|
1 track | The full length of the bar, or the full circle of the ring: the whole range from min to max. |
2 indicator | The part of the track drawn in the indicator color of the meter's status: the fraction of the range up to the value. It meets the rest of the track, or stands a gap from it (separation). |
3 stop-indicator · 任意 | A dot at the end of a bar's track that marks where the range ends, drawn whenever its size is above 0. |
プロパティ
| プロパティ | 型 | 既定値 | 説明 |
|---|---|---|---|
variant | linear | circular | "linear" | Linear is a bar that fills the width its layout gives it; circular is a ring of a fixed size, for tight places and beside text. A structural choice drawn by code, not a token axis, as the progress indicator's is. |
size | small | medium | large | "medium" | The bar's thickness or the ring's box, the progress indicator's three sizes by default (2 / 4 / 8 and 16 / 24 / 40). A design system may add values. |
separation | auto | divider | gap | "auto" | How the indicator is told from the rest of its track. divider: drawn on the track with no space between them. gap: empty space between them. Auto takes comp.meter.track.separation, which follows the design system's choice. |
value | number | 0 | Where the measured quantity stands, between min and max. Always a number: a meter has no unknown value, and a task under way is a progress indicator. |
min | number | 0 | The low end of the range. |
max | number | 1 | The high end of the range. |
status | default | info | success | warning | error | "default" | What the product says the value means, in the names the tag and the snackbar use: default draws the indicator in the meter's own color; info, success, warning and error in that status's color. The product decides it — the meter has no thresholds of its own — and it changes colors only: the words that say so are valueText's and the product's. |
label | string | "" | The accessible name: what is measured ("Storage used"). Required: a bar alone is not a name. |
valueText | string | "" | How assistive technology reads the value when a percentage is not the natural reading ("12.4 GB of 15 GB", "Strong"). Empty reads the platform's percentage. Where status means something, say it here too ("Almost full: 14.2 GB of 15 GB"). |
状態
振る舞い
EARS 記法による要件です。各プラットフォームの実装は、この ID に対応するテストで検証されます。要件の原文は仕様ファイルのものをそのまま掲載しています。
| ID | 要件 |
|---|---|
MTR-1 | THE meter SHALL draw the indicator over the fraction (value − min) / (max − min) of the track, from the track's start: the inline-start of a bar, the top of a ring, turning clockwise. |
MTR-2 | THE meter SHALL draw a bar comp.meter.linear.thickness.medium high for medium (and so on for each size) across the full inline size its layout gives it, and a ring whose outer edge fills a comp.meter.circular.size.medium square with a stroke of comp.meter.circular.thickness.medium for medium (and so on for each size). |
MTR-3 | THE meter SHALL draw the track in comp.meter.track.color and the indicator over it in the indicator color of its status — comp.meter.indicator.color WHILE status is default, comp.meter.info.indicator.color WHILE it is info, comp.meter.success.indicator.color WHILE it is success, comp.meter.warning.indicator.color WHILE it is warning and comp.meter.error.indicator.color WHILE it is error; the ends of a bar's track and indicator SHALL be rounded by comp.meter.track.shape, clamped to half the thickness, and a ring's arcs SHALL have round caps unless comp.meter.track.shape is sys.shape.corner.none. |
MTR-4 | THE meter SHALL tell the indicator from the rest of its track as its separation names — WHILE separation is auto, as comp.meter.track.separation names; WHILE it is divider or gap, as that value names — and WHILE the separation is gap and value lies strictly between min and max SHALL leave comp.meter.track.gap of empty space, measured along the track, between the indicator and the rest of the track (on a ring, at both ends of the indicator's arc); WHILE it is divider THE meter SHALL draw the indicator on the track with nothing between them. |
MTR-5 | WHILE comp.meter.stop-indicator.size is above 0 THE meter SHALL draw at the end of a bar's track a round dot of that size, centred across the track, in the indicator color of its status; a ring SHALL draw none. |
MTR-6 | WHEN value, min, max or status changes after the first frame THE meter SHALL move the indicator's end to the new fraction over comp.meter.motion.value-duration with comp.meter.motion.value-easing, and change the indicator's color over the same duration; WHEN it changes again during that motion THE meter SHALL go on from the place and the color then shown. THE meter SHALL draw its first frame at its value and in its status's color without a motion, and WHERE reduced motion is requested SHALL move the end at once and keep the change of color as a fade over the same duration. |
MTR-7 | THE meter SHALL expose to assistive technology a meter — the platform's own meter where it has one, and otherwise an element with a value range and no busy state — named by label, with min and max as its range, the clamped value as its current value, and valueText as the value's text WHILE valueText is not empty; it SHALL NOT expose the progressbar role or a busy state, because nothing is under way. |
MTR-8 | THE meter SHALL NOT be focusable, SHALL take no input and SHALL NOT announce a change of its value or its status by itself; assistive technology SHALL read the current value when it reaches the meter. |
MTR-9 | THE meter SHALL expose nothing of status by itself: status SHALL change the indicator's color and nothing else, so that what the color means reaches every person only through the words the product gives in valueText, label or the text beside the meter. |
MTR-10 | IF value is below min or above max THE meter SHALL draw and expose it clamped to that range; IF value is not a finite number THE meter SHALL draw and expose min; IF max is not greater than min THE meter SHALL draw the track with no indicator and expose a current value of 0 in a range of 0 to 1; in each case debug builds SHALL report the values. |
MTR-11 | WHEN size names a value that the active design system does not have, or variant, separation or status a value the meter does not define, THE meter SHALL render with the default value's tokens (medium, linear, auto, default), and in debug builds report the unknown value. |
MTR-12 | WHERE the layout direction is right-to-left THE meter SHALL fill a bar from the right and draw its stop indicator at the left; a ring SHALL NOT be mirrored: it starts at the top and turns clockwise in every direction, as a clock does. |
MTR-13 | THE meter SHALL take its layout direction from where it is used and SHALL have no direction setting of its own; WHEN that direction changes while the meter is shown THE meter SHALL draw itself for the new direction at once, without a motion of its own, keeping its value. |
MTR-14 | WHILE label is empty THE meter SHALL still render, and in debug builds report that it has no accessible name. |
MTR-15 | WHERE the platform draws with a person's own forced colors THE meter SHALL draw its track as an edge sys.border.hairline wide in the platform's text color and its indicator filled in the platform's text color, whatever its status, so that the value is still read from where the indicator ends. |
MTR-16 | WHERE the platform has ARIA attributes (the web), the host carries its meter role (MTR-7) itself, so what the product writes on it is not moved, but for a name: WHILE label is not empty THE meter SHALL hold the product's aria-label and aria-labelledby on that host as their data-aria- twins, so that label is its whole name although the platform gives aria-labelledby the precedence, and WHEN label is emptied SHALL give them back as they were written; WHILE label is empty a name the product gives so — aria-label, or aria-labelledby naming an element — SHALL be its name and SHALL NOT be reported as having none in debug builds (MTR-14). WHEN the product removes one, or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaLabelledByElements) to null, THE meter SHALL take it away. |
プラットフォーム別の名前対応
パリティは API が同一であることを意味しません。同じ契約を、各プラットフォームの流儀で表現します。
| 仕様 | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
|---|---|---|---|---|---|
| コンポーネント | tanrei-meter | TanreiMeter | TanreiMeter | TanreiMeter | Meter |
variant · プロパティ | variant | variant | variant | variant | variant |
size · プロパティ | size | size | size | size | size |
separation · プロパティ | separation | separation | separation | separation | separation |
value · プロパティ | value | value | value | value | value |
min · プロパティ | min | bounds.lowerBound | valueRange.start | min | min |
max · プロパティ | max | bounds.upperBound | valueRange.endInclusive | max | max |
status · プロパティ | status | status | status | status | status |
label · プロパティ | label | label | label | label | label |
valueText · プロパティ | valueText | valueText | valueText | valueText | valueText |
| 備考 | Drawn as the progress indicator is (the two share the drawing code; the meter never runs the indeterminate animation). The host carries role="meter", aria-valuemin, aria-valuemax, aria-valuenow, aria-label and aria-valuetext while value-text is set. separation and status are attributes; auto reads the name in --tanrei-comp-meter-track-separation. | TanreiMeter("Storage used", value: 9.3, in: 0...15). Exposed as SwiftUI exposes a Gauge: an element with the label and an accessibility value, accessibilityValue(valueText) while it is set; no updates-frequently trait. | Semantics progressBarRangeInfo with the range (Android has no separate meter role) and stateDescription from valueText; never the indeterminate range info. | Semantics(label:, value:) with the value text or the percentage; on the web renderer the role is meter. | accessibilityRole="progressbar" is not used; the view carries accessibilityValue={{ min, max, now, text }} with role="meter" where React Native passes it through (web), and the label. |
トークン
| トークン | 参照先 | 解決値（ライト） |
|---|---|---|
--tanrei-comp-meter-circular-size-large | comp.progress-indicator.circular.size.large | 40px |
--tanrei-comp-meter-circular-size-medium | comp.progress-indicator.circular.size.medium | 24px |
--tanrei-comp-meter-circular-size-small | comp.progress-indicator.circular.size.small | 16px |
--tanrei-comp-meter-circular-thickness-large | comp.progress-indicator.circular.thickness.large | 2px |
--tanrei-comp-meter-circular-thickness-medium | comp.progress-indicator.circular.thickness.medium | 2px |
--tanrei-comp-meter-circular-thickness-small | comp.progress-indicator.circular.thickness.small | 2px |
--tanrei-comp-meter-error-indicator-color | sys.color.error | |
--tanrei-comp-meter-indicator-color | comp.progress-indicator.indicator.color | |
--tanrei-comp-meter-info-indicator-color | sys.color.info | |
--tanrei-comp-meter-linear-thickness-large | comp.progress-indicator.linear.thickness.large | 8px |
--tanrei-comp-meter-linear-thickness-medium | comp.progress-indicator.linear.thickness.medium | 4px |
--tanrei-comp-meter-linear-thickness-small | comp.progress-indicator.linear.thickness.small | 2px |
--tanrei-comp-meter-motion-value-duration | comp.progress-indicator.motion.value-duration | 300ms |
--tanrei-comp-meter-motion-value-easing | comp.progress-indicator.motion.value-easing | cubic-bezier(0.2, 0, 0, 1) |
--tanrei-comp-meter-stop-indicator-size | comp.progress-indicator.stop-indicator.size | 0px |
--tanrei-comp-meter-success-indicator-color | sys.color.success | |
--tanrei-comp-meter-track-color | comp.progress-indicator.track.color | |
--tanrei-comp-meter-track-gap | comp.progress-indicator.track.gap | 4px |
--tanrei-comp-meter-track-separation | comp.progress-indicator.track.separation | 0 |
--tanrei-comp-meter-track-shape | comp.progress-indicator.track.shape | 9999px |
--tanrei-comp-meter-warning-indicator-color | sys.color.warning |
フィクスチャ
基準となる描画パターンです。全プラットフォームが同じ ID でスナップショットを撮り、結果を比較できるようにしています。
size: small (2)
linear-small
size: small value: 0.62 label: Storage used circular-small
variant: circular size: small value: 0.62 label: Battery size: medium (14)
linear
value: 0.62 label: Storage used valueText: 9.3 GB of 15 GB linear-info
value: 0.4 status: info label: Monthly quota linear-success
value: 0.9 status: success label: Password strength valueText: Strong linear-warning
value: 0.85 status: warning label: Storage used valueText: Almost full: 12.8 GB of 15 GB linear-error
value: 0.98 status: error label: Storage used valueText: Full: 14.7 GB of 15 GB linear-empty
value: 0 label: Storage used linear-full
value: 1 label: Storage used linear-range
value: 37 min: 0 max: 50 label: Seats taken valueText: 37 of 50 seats linear-gap
separation: gap value: 0.62 label: Storage used linear-divider
separation: divider value: 0.62 label: Storage used linear-on-container-highest
value: 0.62 label: Storage used linear-rtl
value: 0.62 label: Storage used direction: rtl circular
variant: circular value: 0.62 label: Battery circular-warning
variant: circular value: 0.15 status: warning label: Battery valueText: Low: 15% size: large (2)
linear-large
size: large value: 0.62 label: Storage used circular-large
variant: circular size: large value: 0.62 label: Battery 生成元 specs/meter.spec.json, tokens/comp/meter.tokens.json, design/tokens/
本当の最小値と最大値がある範囲の中で、ある量がどこにあるかを示すときに使います。割り当てに対するストレージの使用量、電池の残量、部屋の予約済みの席、新しいパスワードの強さなどです。示すのは量で、何かが進行中なわけでも、いつか終わるわけでもありません。
アップロード、インポート、時間のかかる保存のように、実行中のタスクには、代わりにプログレスインジケーターを使います。見た目は同じですが、支援技術は何かが進行中だと伝えます。メーターはそう伝えてはいけません。メッセージの件数のように、意味のある最大値がない値はどちらでもなく、テキストで示します。
| バリアント | 用途 |
|---|---|
| Linear | ページやセクションに属する量。設定ページのストレージ、カードの中の割り当て、プランの一覧の行など。バーはレイアウトが与える幅いっぱいに伸びます。 |
| Circular | 狭い場所や、テキストの横での量。ステータスバーの電池、デバイスの一覧の行など。リングの大きさは固定です。 |
| サイズ | 既定のシステムでのバーの太さ / リングの大きさ | 用途 |
|---|---|---|
| Small | 2 / 16 | 密度の高い行、小さなテキストの横。 |
| Medium | 4 / 24 | ほとんどの場所。既定値です。 |
| Large | 8 / 40 | アカウントのストレージのページのように、その画面の主役である量。 |
サイズ、トラック、既定の色はプログレスインジケーターと同じなので、メーターとプログレスインジケーターを並べてもそろいます。デザインシステムは、メーター自身のトークンで、メーターだけを変えられます。
値が何を意味するかを、メーターは決めません。多いほうが良いのか悪いのかは、プロダクトが知っていることです。ストレージがほぼいっぱいなら warning、パスワードがほぼ最大の強さなら success です。ステータスはプロダクトが計算して渡します。ステータスの名前は、タグとスナックバーと同じです。
| ステータス | 用途 |
|---|---|
| Default | 何も言う必要のない量。ほとんどのメーターはこれです。 |
| Info | 知っておく価値はあるが、何も求めない量。まもなくリセットされる割り当てなど。 |
| Success | あるべきところにある量。強いパスワードなど。 |
| Warning | 近いうちに注意が必要な量。ほぼいっぱいのストレージや、残りわずかの電池など。 |
| Error | すでに何かを止めている量。いっぱいになったストレージなど。 |
ステータスが変えるのはインジケーターの色だけです。その意味は言葉でも伝えます。値のテキストと、メーターの横のテキストです。
- 何を測っているかを表すラベルを付けます。「メーター」ではなく「ストレージの使用量」です。横にキャプションを表示するなら、同じ言葉を使います。
- パーセントが自然な読み方でないときは、値のテキストを使います。「15 GB 中 9.3 GB」「50 席中 37 席」「強い」などです。
- ステータスに意味があるときは、値のテキストにも入れます。「残りわずか：15 GB 中 12.8 GB」のようにします。
- 実行中のタスクに使わない。それはプログレスインジケーターです。
- ステータスの色だけに頼らない。色が見えない人にも、ストレージがほぼいっぱいだと伝わらなければなりません。
- 範囲の外の値を示さない。メーターは範囲に収めて描き、伝えるので、聞こえる数は手元の数と違ってしまいます。
- ロール
meter- ラベル付け
- label is the accessible name. valueText, when given, replaces the platform's percentage as the spoken value. A visible caption beside the meter is the product's composition; when it exists, use the same words as label. status is never announced: say in valueText what it means.
- 最小ターゲット
- 見た目のサイズが小さくても、ヒット領域は最小ターゲットサイズを満たします。 minimum 32px · pointer 44px · spacing 8px · touch 48px
キーボード操作
| キー | 動作 |
|---|
備考
- Not interactive: the meter takes no input and is never focusable (MTR-8), so the minimum target holds without extending anything.
- A meter shows where a value stands in a known range; it is not progress (WAI-ARIA APG, Meter: not for loading or percent completion) and not for a value without a meaningful maximum. A task under way is a progress indicator.
- The value is read from the boundary between indicator and track, so every indicator color — default and the four statuses — must stay at least 3:1 against comp.meter.track.color and the surface behind it (WCAG 1.4.11). In the default system each is above 4.6:1 in light and 7.3:1 in dark.
- Color is never the only sign of a status (WCAG 1.4.1): MTR-9.
- Web: the host carries role="meter" and the aria-value attributes; the native <meter> element is not drawn, because its look cannot be styled in every engine.
生成元 specs/meter.spec.json, tokens/sys/measure.tokens.json
- メーターのロールを公開し、ラベルを名前にします。範囲、現在の値（範囲に収めたもの）、値のテキストがあればそれも公開します。ビジー状態や、タスクが進行中であることは伝えません。
- フォーカスを受け取らず、変化を自分から読み上げません。支援技術は、利用者がたどり着いたときに現在の値を読みます。
- ステータスをそれだけで読み上げることはありません。変わるのは色だけです。
- 値が変わるとインジケーターの端が動き、ステータスが変わると色がフェードします。動きを減らす設定のときは、端はすぐに動き、色だけがフェードします。
- 強制カラーモードでは、ステータスにかかわらず、トラックは細い縁に、インジケーターは塗りつぶしになり、どちらもテキストの色で描かれます。値は、インジケーターの終わる位置で読み取れます。
- 空のラベル、範囲の外の値、数でない値、未知の
size、variant、separation、statusは、デバッグビルドで報告されます。
- ステータスが意味することを言葉で伝えます。値のテキストと、メーターの横のテキストです。
- ストレージがいっぱいになったときのように、重要な変化は自分で知らせます。ライブリージョンのメッセージか、利用者が目にする通知です。メーターは知らせません。
- インジケーターの色（既定と 4 つのステータス）を変えるときは、どれもトラックと背後のサーフェスに対して 3:1 以上を保ちます。値は、インジケーターとトラックの接する位置で読み取られます。既定のシステムでは、5 色ともライトで 4.6:1 以上、ダークで 7.3:1 以上です。