跳到主要内容
此页面尚未翻译成简体中文,暂以英文显示。
menu palettetanreidark_modetranslate

颜色模式

对比度

设计系统

案例展示中的系统模仿其他设计系统,用来展示 Tanrei 能做到什么程度。它们只是示例,不是 Tanrei 支持的设计。

复制链接编辑主题
palettetanrei

颜色模式

对比度

设计系统

案例展示中的系统模仿其他设计系统,用来展示 Tanrei 能做到什么程度。它们只是示例,不是 Tanrei 支持的设计。

复制链接编辑主题
开始使用WebReactSwiftUIJetpack ComposeFlutterReact Native预设你自己的设计系统与 AI 代理一起使用 Tanrei品牌设计令牌设计系统与定制Theme Studio颜色字体排印图标形状层级动效交互状态行为布局尺寸与密度无障碍文字颜色令牌字阶令牌形状令牌层级令牌动效令牌状态令牌间距与度量令牌组件按钮主操作按钮分段按钮cupertino, m3-like 提供按钮组带菜单的按钮工具栏复制按钮复选框单选按钮开关纸片(Chip)菜单滑块滑块字段日历DateTimePicker字段组单选组复选框组下拉选择框下拉选择字段菜单栏文件上传文件选择器 进阶放置区Rating文本输入框 进阶文本字段纸片字段字段组合框 进阶组合框字段数字输入框 进阶数字字段颜色输入框 进阶颜色字段一次性验证码输入框 进阶一次性验证码字段嵌入式文本输入框 进阶聊天输入栏卡片分隔线模态层 进阶对话框列表列表行底部面板侧边面板轮播代码块表格弹出框步骤折叠面板描述列表图示应用外壳页头树视图时间线图片预览调整手柄可调整大小的框Split view滚动区域尺寸过渡徽标进度指示器计量条数字滚动器加载指示器消息条(Snackbar)工具提示键盘快捷键标签(Tag)行内代码提示块(Callout)头像空状态标签组(Tag group)骨架屏文件项色块跑马灯文本标签页标签页视图应用栏导航栏导航抽屉搜索链接分页上一页/下一页链接步骤条面包屑目录链接卡片FAB 菜单m3-like 提供状态Tanrei 是如何构建的参与贡献许可与致谢
首页组件Rating

Rating

Lets a person give a score out of a few marks — stars by default — or shows a score already given, a whole mark or, where the product allows it, a half mark at a time.

content_copy以 Markdown 格式查看
类别
选择
令牌
comp.rating
层级
基础

Overview

Web
tanrei-rating
clock_loader_40
SwiftUI
TanreiRating
radio_button_unchecked
Jetpack Compose
TanreiRating
radio_button_unchecked
Flutter
TanreiRating
radio_button_unchecked
React Native
Rating
radio_button_unchecked

Generated from docs/status/status.json, specs/rating.spec.json

A score to give, and an average to read

Usage

The Web and React samples show the current spec. SwiftUI, Compose, Flutter and React Native are planned: they do not ship a rating yet.

<tanrei-rating name="score" label="Your rating of this recipe"></tanrei-rating>

<!-- Words for each score, in your language; shown beside the rating while a person points. -->
<tanrei-rating
  label="Your rating"
  option-labels='["Poor", "Fair", "Good", "Very good", "Excellent"]'
></tanrei-rating>
<span id="words"></span>

<!-- An average, read only. -->
<tanrei-rating label="Average rating" value="4.5" read-only value-text="4.5 out of 5 stars"></tanrei-rating>

<script type="module">
  import '@tanrei/web/components/rating';
  const rating = document.querySelector('tanrei-rating[option-labels]');
  rating.addEventListener('change', (event) => save(event.detail.value));
  rating.addEventListener('preview', (event) => {
    const score = event.detail.value ?? rating.value;
    document.querySelector('#words').textContent = score ? rating.optionLabels[score - 1] : '';
  });
</script>
import { Rating } from '@tanrei/react';

<Rating label="Your rating of this recipe" value={score} onChange={(event) => setScore(event.detail.value)} />
<Rating
  label="Your rating"
  optionLabels={['Poor', 'Fair', 'Good', 'Very good', 'Excellent']}
  onPreview={(event) => setPointed(event.detail.value)}
/>
<Rating label="Average rating" value={average} readOnly valueText={`${average} out of 5 stars`} />

Specs

Sizes: small, medium and large

Halves, another glyph, ten marks and disabled

Anatomy

Anatomy

Drawn over the fixture empty, as the web package draws it.
Part Description
1 container The round area behind each mark that carries hover, focus and press: the state layer is drawn on it. One per mark, side by side with no space between them.
2 mark The glyph of one step of the score (star by default), drawn filled while it is within the value and outlined while it is not; a half value draws its last mark filled on its start half only.
3 focus-ring Gap-then-ring indicator around the focused mark's container (around every mark while the rating is a slider, RAT-4).

Measurements

Measurements

Length Token Value (px)
container size tanrei.comp.rating.container.size.medium 32
mark size tanrei.comp.rating.mark.size.medium 24
Drawn over the fixture empty, as the web package draws it.

Properties

Property Type Default Description
value number 0 The score: a number of marks from 0 to max, in whole marks or, while allowHalf is true, in halves. 0 is no score yet.
max number 5 How many marks are drawn: the highest score. A whole number from 1.
allowHalf boolean false Lets a person give a score that ends on a half mark: a press on the start half of a mark gives that mark less a half, and the arrow keys move by a half. A read-only rating shows halves whatever it says (RAT-14).
size small | medium | large "medium" The size of each mark (20 / 24 / 32) and of the round area behind it (28 / 32 / 40). The hit area always meets the minimum target. A design system may add values.
icon string "" The name of the glyph of one mark in the system's icon set (favorite, thumb_up); empty draws star. One glyph for every mark; the filled and the outlined forms are the icon set's two fills.
label string "" Names the rating for assistive technology ("Your rating of this recipe"). Required. Never drawn: a visible question beside the rating is the product's, and uses the same words.
optionLabels strings The name of each score a person can give, in ascending order from the lowest (one mark, or a half mark while allowHalf is true): ["Poor", "Fair", "Good", "Very good", "Excellent"]. Empty names each score by its number, written as the platform writes a number in the language of the element.
valueText string "" How assistive technology reads a read-only rating's score ("4.5 out of 5 stars"), in the product's language. Empty reads the score's name from optionLabels, or its number.
readOnly boolean false Shows a score that cannot be changed — an average, a review's score — as one image with a name: not focusable and not pressable.
disabled boolean false Shows the rating as unavailable: drawn in the disabled colors, not focusable, taking no input and left out of form submission.

Events

Event Description
change The person changed the score: a press on a mark or a key. Carries the new value. Not emitted when the product sets value.
preview A fine pointer moved onto a mark, or off the rating: carries the score the pointer would give, or null when it leaves, so that the product can show that score's words while the person points ("Very good").

States

Behavior

Requirements in EARS form. Every platform implementation is tested against these ids.

ID Requirement
RAT-1 THE rating SHALL draw max marks in a row from its inline-start edge, each the glyph icon names (star WHILE icon is empty) at comp.rating.mark.size.medium for size medium (and so on for each size), centred in a round container comp.rating.container.size.medium across (and so on), with the containers touching: the marks within value SHALL be drawn from the selected condition — sys.icon.family.selected, sys.icon.fill.selected and comp.rating.selected.mark.color — and the others from the unselected condition — sys.icon.family.unselected, sys.icon.fill.unselected and comp.rating.unselected.mark.color — with sys.icon.weight and an optical size clamped between sys.icon.optical-size.min and sys.icon.optical-size.max.
RAT-2 WHILE value ends on a half mark THE rating SHALL draw that mark twice in its place — from the selected condition clipped to its inline-start half and from the unselected condition clipped to its inline-end half, divided at the glyph's centre line — so that one mark reads as half filled, its filled half on the right WHERE the layout direction is right-to-left.
RAT-3 WHILE readOnly is false, disabled is false, allowHalf is false and max is at most 7 THE rating SHALL be a radio group named by label, each mark a radio named by its entry in optionLabels or, WHILE optionLabels has no entry for it, by its score written as the platform writes a number in the language of the element, checked WHILE its score equals value, with one stop in the focus order: the checked mark, or the first mark WHILE value is 0; THE rating SHALL answer the keys as a radio group does (RGP-5, RGP-6) — Right Arrow and Down Arrow check the next mark, Left Arrow and Up Arrow the previous one, both wrapping, Left and Right exchanged WHERE the layout direction is right-to-left, Space checks the focused mark — and emit change once for each change of value.
RAT-4 WHILE readOnly is false, disabled is false, and allowHalf is true or max is above 7 THE rating SHALL be one slider named by label, from 0 to max, with value as its current value and as its value text the entry of optionLabels for value or, WHILE there is none, nothing, so that the platform reads the number; it SHALL be one stop in the focus order and SHALL answer the keys as a slider does: Right Arrow and Up Arrow raise the value by one step — a half while allowHalf is true, a whole mark otherwise — and Left Arrow and Down Arrow lower it, never below one step and never above max (Right and Left exchanged WHERE the layout direction is right-to-left), Page Up and Page Down by one whole mark, Home to one step and End to max, and emit change once for each change of value.
RAT-5 WHILE readOnly is true and disabled is false THE rating SHALL draw its value as RAT-1 and RAT-2 say, SHALL take no press, no key and no focus, and SHALL expose itself as one image named by label and described by valueText or, WHILE valueText is empty, by the entry of optionLabels for value or else value written as the platform writes a number in the language of the element; WHILE value is 0 it SHALL be described as such by valueText alone, and in debug builds SHALL report a read-only rating with neither valueText nor a value above 0.
RAT-6 WHEN the user presses a mark by pointer or touch, or Space on a focused mark (RAT-3), WHILE readOnly and disabled are false THE rating SHALL set value to that mark's score — to that mark less a half WHILE allowHalf is true and the press lands on the mark's inline-start half — and WHEN that differs from value emit change once with the new value; a press on the mark of the score already given SHALL change nothing, so that no input takes a score back to 0.
RAT-7 WHILE a fine pointer is over a mark and readOnly and disabled are false THE rating SHALL draw every mark as RAT-1 and RAT-2 would draw them for the score the pointer would give (RAT-6), with that mark's container in its hovered state, and emit preview with that score each time it changes; WHEN the pointer leaves the rating THE rating SHALL draw its value again and emit preview once with null.
RAT-8 WHERE a mark's container is below the minimum target THE rating SHALL extend that mark's 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; WHERE the hit areas of neighbouring marks overlap, a point SHALL belong to the mark whose centre is nearer, so that the row is divided at the middle between marks.
RAT-9 WHEN a mark is pressed by pointer, touch or Space THE rating SHALL show the pressed state on that mark's container without delay and SHALL keep it visible for at least sys.motion.duration.press-hold, even when the press ends sooner.
RAT-10 WHILE pressed THE rating 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; mark, 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.rating.motion.feedback-duration with motion.state-easing, fades over motion.state-duration with motion.state-easing once the press has ended and press-hold has passed, and appears whole where motion is reduced.
RAT-11 THE rating 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) — around the focused mark's container while it is a radio group, around the row of containers while it is a slider — at sys.focus.offset, never for focus gained by pointer; a platform that cannot draw a choice SHALL fall back to the first value and state that in its README.
RAT-12 WHEN value changes THE rating SHALL change each mark between its unselected and its selected form over comp.rating.motion.selection-duration with comp.rating.motion.selection-easing, as a fade between the two forms, going on from the form then shown WHEN it changes again during the motion (MOT-2), and SHALL change its containers' state colors over comp.rating.motion.state-duration with comp.rating.motion.state-easing; THE rating SHALL draw its first frame at its value without a motion (MOT-3), and WHERE motion is reduced the fades stay (MOT-6).
RAT-13 WHILE disabled is true THE rating SHALL render its containers and marks from the disabled tokens of each mark's condition, SHALL NOT be focusable or take any input, SHALL emit nothing, SHALL expose its disabled state and its value to assistive technology, and SHALL be left out of form submission.
RAT-14 WHEN the product sets value THE rating SHALL draw the new value and SHALL NOT emit change; IF value is below 0 or above max THE rating SHALL draw and expose it clamped to that range, and IF it is not a multiple of a half, or not a whole number while allowHalf is false and the rating is not read-only, SHALL draw and expose the nearest score it can show — a read-only rating shows halves whatever allowHalf says, so that an average is drawn to the nearest half; IF max is not a whole number from 1 THE rating SHALL take the whole number below it and at least 1; in each case debug builds SHALL report the value.
RAT-15 WHERE the platform has forms (the web) THE rating SHALL take part in them as a native control does: it takes name, submits value WHILE it is above 0 and nothing WHILE it is 0, restores it on navigation and resets to the value it was first given, and Enter while it has focus submits its form as Enter in a native radio does; WHILE readOnly is true it SHALL submit its value, and WHILE disabled is true nothing.
RAT-16 WHERE the layout direction is right-to-left THE rating SHALL draw its first mark at the right, the score growing leftward, and SHALL draw the glyph mirrored as RAT-19 says; it SHALL take its layout direction from where it is used and have no direction setting of its own.
RAT-17 WHERE the platform draws with a person's own forced colors THE rating SHALL draw every mark in the platform's text color — the selected form filled and the unselected form outlined, so that the score is read from the shapes and not from a color — the hovered mark's container in the platform's highlight color, and a disabled rating in the platform's disabled text color.
RAT-18 WHILE label is empty THE rating SHALL still render and in debug builds report that it has no accessible name; WHILE optionLabels is not empty and does not hold exactly one entry for each score a person can give THE rating SHALL use the entries it has, name the others by their numbers, and in debug builds report the count; WHEN size names a value the active design system does not have THE rating SHALL render with medium's tokens and in debug builds report the unknown value; WHILE icon names no glyph of the system's icon set THE rating SHALL draw star and in debug builds report the name.
RAT-19 WHERE the layout direction is right-to-left THE rating SHALL draw the glyph of its marks mirrored left to right exactly when the system's icon set marks that glyph's name as mirrored or — for the glyph icon names — the product forces mirroring for that use, and unmirrored when the product forbids it: the icon helper mirrors the glyph inside each mark's box, about the box's vertical centre line, changing neither the marks' places, sizes and colors nor the halves RAT-2 draws. The star the rating draws while icon is empty is its own glyph and takes no word of the product's. THE rating SHALL NOT mirror a mark itself.
RAT-20 WHEN the control height (dial.control.height) changes THE rating SHALL keep its own size: a mark's container (comp.rating.container.size.medium, and so on for each size) is the pitch of a row of glyphs, which follows the size of its mark (comp.rating.mark.size.medium, and so on), and no control of a row's height, so THE rating SHALL draw its containers and marks at their own sizes at every control height; a person's reach is the hit area's, which SHALL still meet the minimum target around each mark (RAT-8), not a wider pitch between the marks.

Platform name mapping

Parity does not mean identical APIs. Each platform uses its own idiom for the same contract.

Spec Web SwiftUI Jetpack Compose Flutter React Native
Component tanrei-rating TanreiRating TanreiRating TanreiRating Rating
value · Property value value value value value
max · Property max maximum max max max
allowHalf · Property allowHalf allowsHalf allowHalf allowHalf allowHalf
size · Property size size size size size
icon · Property icon systemImage icon icon icon
label · Property label label label label label
optionLabels · Property optionLabels optionLabels optionLabels optionLabels optionLabels
valueText · Property valueText valueText valueText valueText valueText
readOnly · Property readOnly isReadOnly readOnly readOnly readOnly
disabled · Property disabled .disabled(_:) enabled enabled disabled
change · Event change value (Binding) onValueChange onChanged onValueChange
preview · Event preview onPreview onPreview onPreview onPreview
Notes Form-associated. As a radio group, the shadow root holds one element with role="radiogroup" and aria-label, and one role="radio" element per mark with a roving tabindex — not <input type="radio">, whose name group cannot span shadow roots; as a slider, one role="slider" element with aria-valuemin="0", aria-valuemax, aria-valuenow and aria-valuetext while an entry names the value; read-only, one role="img" element with aria-label and aria-description. optionLabels is an array property whose attribute option-labels is read as a JSON array. allow-half, read-only, value-text are the attributes. A half mark is two glyphs in one box, each clipped with clip-path: inset() on its half, the halves swapped in right-to-left. change and preview are CustomEvents whose detail.value is the score (null for preview's leaving). Every mark carries the container part and its glyphs the mark part. data-mirror (auto, the default; always; never) on the rating is the product's word on mirroring the glyph icon names (RAT-19), as on a glyph the product places itself; the star drawn while icon is empty takes none. TanreiRating("Your rating", value: $score). Exposed as one adjustable element (accessibilityAdjustableAction) in every mode, because VoiceOver has no radio group: swipe up and down move by a step; the radio-group mode's semantics apply where a platform has them. Radio-group mode: Modifier.selectableGroup() with each mark selectable(role = Role.RadioButton); slider mode: progressSemantics with setProgress; read-only: Role.Image with the description. enabled is the inverse of disabled. Radio-group mode: each mark Semantics(inMutuallyExclusiveGroup: true, checked:); slider mode: Semantics(slider: true, value:, increasedValue:, decreasedValue:); read-only: Semantics(image: true). A null onChanged is disabled. Radio-group mode: accessibilityRole="radiogroup" with each mark role="radio" and accessibilityState.checked; slider mode: accessibilityRole="adjustable" with accessibilityActions increment and decrement; read-only: accessibilityRole="image".

Tokens

Token Aliases Resolved (light)
--tanrei-comp-rating-container-shape sys.shape.corner.full 9999px
--tanrei-comp-rating-container-size-large — 40px
--tanrei-comp-rating-container-size-medium — 32px
--tanrei-comp-rating-container-size-small — 28px
--tanrei-comp-rating-disabled-container-shape — 9999px
--tanrei-comp-rating-disabled-opacity — 1
--tanrei-comp-rating-focused-container-shape — 9999px
--tanrei-comp-rating-focused-opacity — 1
--tanrei-comp-rating-hovered-container-shape — 9999px
--tanrei-comp-rating-hovered-opacity — 1
--tanrei-comp-rating-mark-size-large sys.icon.large 32px
--tanrei-comp-rating-mark-size-medium sys.icon.medium 24px
--tanrei-comp-rating-mark-size-small sys.icon.small 20px
--tanrei-comp-rating-motion-feedback-duration sys.motion.role.feedback 450ms
--tanrei-comp-rating-motion-selection-duration sys.motion.role.selection.mark 250ms
--tanrei-comp-rating-motion-selection-easing sys.motion.easing.state cubic-bezier(0.2, 0, 0, 1)
--tanrei-comp-rating-motion-state-duration sys.motion.role.state.compact 200ms
--tanrei-comp-rating-motion-state-easing sys.motion.easing.state cubic-bezier(0.2, 0, 0, 1)
--tanrei-comp-rating-pressed-container-shape — 9999px
--tanrei-comp-rating-pressed-opacity — 1
--tanrei-comp-rating-selected-container-color — #000000 · 0%
--tanrei-comp-rating-selected-disabled-container-color — #000000 · 0%
--tanrei-comp-rating-selected-disabled-mark-color — #1b1b1b · 38%
--tanrei-comp-rating-selected-disabled-state-layer-color — #1b1b1b · 38%
--tanrei-comp-rating-selected-focused-container-color — #1b1b1b · 10%
--tanrei-comp-rating-selected-focused-mark-color — #1b1b1b
--tanrei-comp-rating-selected-focused-state-layer-color — #1b1b1b
--tanrei-comp-rating-selected-hovered-container-color — #1b1b1b · 8%
--tanrei-comp-rating-selected-hovered-mark-color — #1b1b1b
--tanrei-comp-rating-selected-hovered-state-layer-color — #1b1b1b
--tanrei-comp-rating-selected-mark-color sys.color.primary #1b1b1b
--tanrei-comp-rating-selected-pressed-container-color — #1b1b1b · 10%
--tanrei-comp-rating-selected-pressed-mark-color — #1b1b1b
--tanrei-comp-rating-selected-pressed-state-layer-color — #1b1b1b
--tanrei-comp-rating-selected-state-layer-color comp.rating.selected.mark.color #1b1b1b
--tanrei-comp-rating-unselected-container-color — #000000 · 0%
--tanrei-comp-rating-unselected-disabled-container-color — #000000 · 0%
--tanrei-comp-rating-unselected-disabled-mark-color — #1b1b1b · 38%
--tanrei-comp-rating-unselected-disabled-state-layer-color — #1b1b1b · 38%
--tanrei-comp-rating-unselected-focused-container-color — #848484 · 10%
--tanrei-comp-rating-unselected-focused-mark-color — #848484
--tanrei-comp-rating-unselected-focused-state-layer-color — #848484
--tanrei-comp-rating-unselected-hovered-container-color — #848484 · 8%
--tanrei-comp-rating-unselected-hovered-mark-color — #848484
--tanrei-comp-rating-unselected-hovered-state-layer-color — #848484
--tanrei-comp-rating-unselected-mark-color sys.color.outline #848484
--tanrei-comp-rating-unselected-pressed-container-color — #848484 · 10%
--tanrei-comp-rating-unselected-pressed-mark-color — #848484
--tanrei-comp-rating-unselected-pressed-state-layer-color — #848484
--tanrei-comp-rating-unselected-state-layer-color comp.rating.unselected.mark.color #848484

Fixtures

Canonical renderings. Every platform snapshots each fixture under the same id so the results can be compared.

Generated from specs/rating.spec.json, tokens/comp/rating.tokens.json, design/tokens/

Guidelines

When to use

Use a rating to ask a person for a score on a short scale — a review of a recipe, a product or a stay — and to show a score already given, such as the average of a product’s reviews in a list. Its marks are the scale: a person sees at once how many there are and how many are given.

For a choice whose options are words rather than steps of one scale, use a radio group. For a value on a long or continuous range, use a slider.

Whole marks and halves

Setting What a person can give What assistive technology meets
Whole marks, up to seven One score per mark A radio group, one radio per mark: the arrow keys check the next or previous mark
Halves, or more than seven marks Every half (or every mark) up to the maximum A slider: the arrow keys move by a step, Page Up and Page Down by a mark, Home and End to the ends
Read only Nothing One image, named by the label and described by the value text

Allow halves only where a person needs that precision. Five stars in halves are ten choices, which takes longer to give. A read-only rating always shows halves, so an average such as 4.3 is drawn as four and a half marks: say the exact value in the value text.

Choosing a size

Size Mark / round area in the default system Use for
Small 20 / 28 A list row, next to small text.
Medium 24 / 32 A form. The default.
Large 32 / 40 The one score a view is about, such as a product’s page.

Whatever the size, each mark takes a whole touch target: neighbouring marks share the space between them at the middle.

Taking a score back

A rating has no way to take a score back to none, by pointer, by key or by assistive technology: a press on the score already given changes nothing, as a radio group has no way to uncheck. If your form must let a person withdraw a score, place a text Button beside the rating that sets its value to 0.

  • Give it a label that says what is scored: “Your rating of this recipe”. If a question is shown next to it, use the same words.
  • Name the scores in your language with optionLabels when the steps mean something (“Poor”, “Excellent”), and show the words beside the rating while a person points (preview).
  • Give a read-only rating a value text that says the score exactly: “4.3 out of 5 stars, 128 reviews”.

Don’t

  • Don’t use a rating for a choice whose options are not steps of one scale.
  • Don’t rely on a colored star alone. The default system draws given marks filled and the others outlined, so the score is read from the shapes; keep that if you change the colors.
  • Don’t use more marks than a person can count at a glance. Ten is the most that stays readable.

Accessibility

Focus order

Each number is a stop of the Tab key, in the order Tab reaches it; Shift+Tab goes back the same way. The component is live: press Tab to follow it. Drawn over the fixture value, as the web package draws it.
    Role
    radiogroup of radios (whole marks, up to 7); slider (half marks, or more than 7 marks); img (read-only)
    Labeling
    label names the radio group, the slider or the read-only image. Each radio is named by its entry in optionLabels or by its number; the slider's value text is the entry for its value, or the platform reads the number. A read-only rating is described by valueText. The marks' glyphs are decorative.
    Minimum target
    The hit area meets the minimum target size even when the visual size is smaller. minimum 36px · pointer 36px · spacing 8px · touch 36px

    Keyboard

    Keys Action
    Tab or Shift Tab Moves focus to the rating — to the checked mark, or to the first mark while there is no score — and out of it. One stop.
    Right Arrow or Down Arrow (radio group) Checks the next mark, wrapping from the last to the first; Left Arrow in a right-to-left layout.
    Left Arrow or Up Arrow (radio group) Checks the previous mark, wrapping from the first to the last; Right Arrow in a right-to-left layout.
    Space (radio group) Checks the focused mark when none is checked. A press on the checked mark changes nothing: a score is never taken back to none.
    Right Arrow or Up Arrow or Left Arrow or Down Arrow (slider) Raises or lowers the score by one step (a half where halves are allowed), between one step and max.
    Page Up or Page Down (slider) Raises or lowers the score by one whole mark.
    Home or End (slider) Sets the lowest score (one step) or the highest (max).
    Enter Submits the form the rating stands in, as in a native radio; it sets no score.

    Notes

    • WAI-ARIA APG: a radio group suits up to seven choices; with more, a slider's keys make choosing faster (the Rating Slider example). Five whole stars are five radios (the Rating Radio Group example); five stars in halves are ten choices, so the rating is a slider (RAT-3, RAT-4).
    • There is no way to take a score back to none once given, by any input, as there is none in a radio group. A product whose form needs it places a Button beside the rating that sets value to 0.
    • The unselected mark is drawn in comp.rating.unselected.mark.color, outline in the default system: a functional boundary of at least 3:1 against the surface, so that the marks not given can be counted (WCAG 1.4.11). The filled and outlined forms differ in shape as well as color (WCAG 1.4.1).
    • Neighbouring marks share their extended hit areas by distance (RAT-8): at size medium each mark has 32 of the row's width, above the 24 that WCAG 2.5.8 asks.

    Generated from specs/rating.spec.json, tokens/sys/measure.tokens.json

    What the component handles

    • With whole marks up to seven, it is a radio group named by the label, each mark a radio named by its entry in optionLabels or by its number in the language of the page. It is one stop in the focus order: the checked mark, or the first while there is no score. The arrow keys check the next or previous mark and wrap, Space checks the focused mark, Enter submits the form.
    • With halves or more than seven marks, it is one slider from 0 to the maximum, its value text the entry of optionLabels for the score. The arrow keys move by a step, Page Up and Page Down by a mark, Home to one step and End to the maximum.
    • Read only, it is one image named by the label and described by the value text. It cannot be focused or pressed.
    • Each mark’s hit area reaches the minimum target without changing what is drawn; neighbouring marks are divided at the middle between them.
    • Marks within the score are drawn filled and the others outlined, so the score never rests on color alone. The outlined marks are held at 3:1 against the surface. With forced colors, every mark is drawn in the text color.
    • Disabled, it is drawn in the disabled colors, cannot be focused, takes no input and is left out of the form, and still exposes its score.
    • An empty label, optionLabels of the wrong length, a value it cannot show, an unknown size and a read-only rating with nothing to describe it are reported in debug builds.

    What you need to do

    • Give every rating a label, and a read-only one a value text.
    • Write the words of optionLabels and valueText in your product’s language.
    • If a score can be withdrawn, give people a Button to do it: the rating has no clear action.