Differential D13340 Diff 37926 source/components/card.rst

Changeset View

Standalone View

source/components/card.rst

This file was added.

1		Card
2		====
3
4		Purpose
5		-------
6
7		A card serves as overview and an entry point for more detailed information and can
8		offer direct access to the most important actions on an item.
9
10		Example
11		-------
12
13		Guidelines
14		----------
15
16		Is this the right control
17		~~~~~~~~~~~~~~~~~~~~~~~~~
18
19		- Don't use a card to display long texts.
20		- Cards can be used to display items with different content types, e.g. images
21		text, videos.
22		- Don't use cards for content that should be directly comparable, use a
23		table view or a grid view for that.
24		- If you would show more than 20 cards at a time, or if the user would have to scroll
25		for more than three screen heights to see all of them, consider using a list instead.
26		- Don't use cards with text input elements.
	martUnsubmitted Not Done what does this line mean? mart: what does this line mean?
	fabianrAuthorUnsubmitted Not Done Changed the suggestion to be more clear. fabianr: Changed the suggestion to be more clear.
27		- Use cards instead of a grid view, if you need more then one action.
28		- If your cards consist, of just one image, a grid with overlay actions,
29		might be more suitable.
30
31		Behavior
32		~~~~~~~~
33
34		\|desktopicon\| Desktop
35		^^^^^^^^^^^^^^^^^^^^^
36
37		Cards are responsive. They resize to fit into the available
38		space.
39
40		.. raw:: html
41
42		<video src="https://cdn.kde.org/hig/video/20180620-1/CardLayout1.webm" loop="true" playsinline="true" width="536" controls="true" onended="this.play()" class="border"></video>
43
44
45		It is recommended that you adjust the number of cards displayed next to each other
46		depending on the available space.
47
48		.. raw:: html
49
50		<video src="https://cdn.kde.org/hig/video/20180620-1/CardLayout2.webm" loop="true" playsinline="true" width="536" controls="true" onended="this.play()" class="border"></video>
51
52		\|mobileicon\| Mobile
53		^^^^^^^^^^^^^^^^^^^
	martUnsubmitted Done number of columns? mart: number of columns?
54
55		- Cards only resize to orientation changes.
56		- The number of columns only adjust to orientation changes.
57
58		Appearance
59		~~~~~~~~~~
60
	martUnsubmitted Not Done how the component works right now is to support one basic layout: image on top, then text, then optional action buttons. some custom content can be put inside/in place of the text, and stuff can be stuffed in the top image as well for other different kind of content there is the "empty" card which is just the white rectangle with shadow, which then becomes completely the app's responsibility on what layout to use in it mart: how the component works right now is to support one basic layout: image on top, then text, then…
	fabianrAuthorUnsubmitted Not Done I would add a implementation section in another patch, and give hints for devs about the existing layouts there. fabianr: I would add a implementation section in another patch, and give hints for devs about the…
61		Cards can have a lot of different layouts, the only common requirement is the
62		container around it. While cards can have a lot of different layouts, each
63		should focus only on one bit of information or content.
64
65		Here are some general recommendations for card layouts:
66
67		- Be visual immersive. Use a lot of images, icon, video elements,
68		different text sizes, ... . Cards are not a control for plain text.
69
70		- Use a well known aspect ration for a header image
71
72		.. image:: /img/Card5.qml.png
73		:alt: Cards with 16x9, 4x3, 1x1 header image aspect ratio
74
75		- Add a padding of at least largeSpacing to the card, except for videos
76		and images. These can ignore the padding and span the entire width or
77		height of a card.
78
79		.. image:: /img/Card2.qml.png
80		:alt: Padding for text and buttons