From 4fcab5752a7c867d6cabd59738560d536c3d0dae Mon Sep 17 00:00:00 2001 From: Jeremy Elbourn Date: Wed, 7 Jun 2017 14:57:27 -0700 Subject: [PATCH] docs(card): add guidance for a11y (#4781) --- src/lib/card/card.md | 36 +++++++++++++++++++++++++--- src/lib/card/card.ts | 56 +++++++++++--------------------------------- 2 files changed, 47 insertions(+), 45 deletions(-) diff --git a/src/lib/card/card.md b/src/lib/card/card.md index eb9644fb06f..37ae6fe3e9b 100644 --- a/src/lib/card/card.md +++ b/src/lib/card/card.md @@ -1,5 +1,4 @@ -`` is a content container for text, photos, and actions. Cards are intended to provide -information on a single subject. +`` is a content container for text, photos, and actions in the context of a single subject. @@ -35,7 +34,7 @@ header to a card. This header can contain: ### Title groups -An `` can be used to combine a title, subtitle, and image into a single section. +`` can be used to combine a title, subtitle, and image into a single section. This element can contain: * `` * `` @@ -43,3 +42,34 @@ This element can contain: * `` * `` * `` + +### Accessibility +Cards can be used in a wide variety of scenarios and can contain many different types of content. +Due to this dynamic nature, the appropriate accessibility treatment depends on how `` is +used. + +#### Group, region, and landmarks +There are several ARIA roles that communicate that a portion of the UI represents some semantically +meaningful whole. Depending on what the content of the card means to your application, +[`role="group"`][0], [`role="region"`][1], or [one of the landmark roles][3] should typically be +applied to the `` element. + +A role is not necessary when the card is used as a purely decorative container that does not +convey a meaningful grouping of related content for a single subject. In these cases, the content +of the card should follow standard practices for document content. + + +#### Focus +Depending on how cards are used, it may be appropriate to apply a `tabindex` to the `` +element. If cards are a primary mechanism through which user interact with the application, +`tabindex="0"` is appropriate. If attention can be sent to the card, but it's not part of the +document flow, `tabindex="-1"` is appropriate. + +If the card acts as a purely decorative container, it does not need to be tabbable. In this case, +the card content should follow normal best practices for tab order. + + + + [0]: https://www.w3.org/TR/wai-aria/roles#group + [1]: https://www.w3.org/TR/wai-aria/roles#region + [2]: https://www.w3.org/TR/wai-aria/roles#landmark diff --git a/src/lib/card/card.ts b/src/lib/card/card.ts index 9140872a0c7..cd8c062761a 100644 --- a/src/lib/card/card.ts +++ b/src/lib/card/card.ts @@ -12,9 +12,7 @@ import { */ @Directive({ selector: 'md-card-content, mat-card-content', - host: { - '[class.mat-card-content]': 'true' - } + host: {'class': 'mat-card-content'} }) export class MdCardContent {} @@ -24,9 +22,7 @@ export class MdCardContent {} */ @Directive({ selector: 'md-card-title, mat-card-title, [md-card-title], [mat-card-title]', - host: { - '[class.mat-card-title]': 'true' - } + host: {'class': 'mat-card-title'} }) export class MdCardTitle {} @@ -36,9 +32,7 @@ export class MdCardTitle {} */ @Directive({ selector: 'md-card-subtitle, mat-card-subtitle, [md-card-subtitle], [mat-card-subtitle]', - host: { - '[class.mat-card-subtitle]': 'true' - } + host: {'class': 'mat-card-subtitle'} }) export class MdCardSubtitle {} @@ -48,9 +42,7 @@ export class MdCardSubtitle {} */ @Directive({ selector: 'md-card-actions, mat-card-actions', - host: { - '[class.mat-card-actions]': 'true' - } + host: {'class': 'mat-card-actions'} }) export class MdCardActions {} @@ -60,9 +52,7 @@ export class MdCardActions {} */ @Directive({ selector: 'md-card-footer, mat-card-footer', - host: { - '[class.mat-card-footer]': 'true' - } + host: {'class': 'mat-card-footer'} }) export class MdCardFooter {} @@ -72,9 +62,7 @@ export class MdCardFooter {} */ @Directive({ selector: '[md-card-sm-image], [mat-card-sm-image]', - host: { - '[class.mat-card-sm-image]': 'true' - } + host: {'class': 'mat-card-sm-image'} }) export class MdCardSmImage {} @@ -84,9 +72,7 @@ export class MdCardSmImage {} */ @Directive({ selector: '[md-card-md-image], [mat-card-md-image]', - host: { - '[class.mat-card-md-image]': 'true' - } + host: {'class': 'mat-card-md-image'} }) export class MdCardMdImage {} @@ -96,9 +82,7 @@ export class MdCardMdImage {} */ @Directive({ selector: '[md-card-lg-image], [mat-card-lg-image]', - host: { - 'class.mat-card-lg-image': 'true' - } + host: {'class': 'mat-card-lg-image'} }) export class MdCardLgImage {} @@ -108,9 +92,7 @@ export class MdCardLgImage {} */ @Directive({ selector: '[md-card-image], [mat-card-image]', - host: { - '[class.mat-card-image]': 'true' - } + host: {'class': 'mat-card-image'} }) export class MdCardImage {} @@ -120,9 +102,7 @@ export class MdCardImage {} */ @Directive({ selector: '[md-card-xl-image], [mat-card-xl-image]', - host: { - '[class.mat-card-xl-image]': 'true' - } + host: {'class': 'mat-card-xl-image'} }) export class MdCardXlImage {} @@ -132,9 +112,7 @@ export class MdCardXlImage {} */ @Directive({ selector: '[md-card-avatar], [mat-card-avatar]', - host: { - '[class.mat-card-avatar]': 'true' - } + host: {'class': 'mat-card-avatar'} }) export class MdCardAvatar {} @@ -157,9 +135,7 @@ export class MdCardAvatar {} styleUrls: ['card.css'], encapsulation: ViewEncapsulation.None, changeDetection: ChangeDetectionStrategy.OnPush, - host: { - '[class.mat-card]': 'true' - } + host: {'class': 'mat-card'} }) export class MdCard {} @@ -175,9 +151,7 @@ export class MdCard {} templateUrl: 'card-header.html', encapsulation: ViewEncapsulation.None, changeDetection: ChangeDetectionStrategy.OnPush, - host: { - '[class.mat-card-header]': 'true' - } + host: {'class': 'mat-card-header'} }) export class MdCardHeader {} @@ -193,8 +167,6 @@ export class MdCardHeader {} templateUrl: 'card-title-group.html', encapsulation: ViewEncapsulation.None, changeDetection: ChangeDetectionStrategy.OnPush, - host: { - '[class.mat-card-title-group]': 'true' - } + host: {'class': 'mat-card-title-group'} }) export class MdCardTitleGroup {}