Skip to content

Commit cd51009

Browse files
adamloblerclaude
adamlobler
and
claude
committed
docs(ui-card): document Card with nested examples and usage guidelines
Adds examples for each size, nested cards at every size, mixed sizes inside one base Card, and a base Card holding several nested Cards with heading and body copy. Adds a do/don't guidelines section for the two composition rules: a base Card must not contain another base Card, and a nested Card needs a surface behind it (a Card, Modal, or utility panel such as Tray) because it has no background colour of its own. Examples use Heading and Text rather than bare strings so example copy picks up token-driven colours and stays legible in dark mode. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1 parent 0331922 commit cd51009

1 file changed

Lines changed: 172 additions & 0 deletions

File tree

‎packages/ui-card/src/Card/v1/README.md‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
---
2+
describes: Card
3+
---
4+
5+
Use `<Card />` as a basic wrapper for grouping related content with padding,
6+
border radius, shadow, and background color.
7+
8+
```js
9+
---
10+
type: example
11+
---
12+
<Card>
13+
<Heading level="h3" margin="0 0 x-small 0">
14+
Base card
15+
</Heading>
16+
<Text variant="content">Medium size, the default.</Text>
17+
</Card>
18+
```
19+
20+
### Sizes
21+
22+
`size` controls padding, border radius, and the card's min-/max-width
23+
breakpoints: `sm` applies a max-width, `md` applies a min- and max-width, and
24+
`lg` applies a min-width.
25+
26+
```js
27+
---
28+
type: example
29+
---
30+
<div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
31+
<Card size="sm">
32+
<Text variant="content">Small card</Text>
33+
</Card>
34+
<Card size="md">
35+
<Text variant="content">Medium card</Text>
36+
</Card>
37+
<Card size="lg">
38+
<Text variant="content">Large card</Text>
39+
</Card>
40+
</div>
41+
```
42+
43+
### Nested cards
44+
45+
The `nested` variant is meant to be placed inside a `base` Card. It omits the
46+
background color and shadow, and uses a smaller border radius. A nested
47+
Card's `size` is independent of its parent's — choose it based on the nested
48+
content's own needs, not to match the parent.
49+
50+
```js
51+
---
52+
type: example
53+
---
54+
<div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
55+
<Card variant="base" size="sm">
56+
<Card variant="nested" size="sm">
57+
<Text variant="content">Nested small card</Text>
58+
</Card>
59+
</Card>
60+
<Card variant="base" size="md">
61+
<Card variant="nested" size="md">
62+
<Text variant="content">Nested medium card</Text>
63+
</Card>
64+
</Card>
65+
<Card variant="base" size="lg">
66+
<Card variant="nested" size="lg">
67+
<Text variant="content">Nested large card</Text>
68+
</Card>
69+
</Card>
70+
</div>
71+
```
72+
73+
### Mixed sizes
74+
75+
Nested Cards don't need to match their parent's size, or each other's — you
76+
can place several different-sized `nested` Cards side by side inside one
77+
larger `base` Card.
78+
79+
```js
80+
---
81+
type: example
82+
---
83+
<Card variant="base" size="lg">
84+
<div style={{ display: 'flex', gap: '1rem', flexWrap: 'wrap' }}>
85+
<Card variant="nested" size="sm">
86+
<Text variant="content">Small nested card</Text>
87+
</Card>
88+
<Card variant="nested" size="md">
89+
<Text variant="content">Medium nested card</Text>
90+
</Card>
91+
</div>
92+
</Card>
93+
```
94+
95+
### Multiple nested cards
96+
97+
A `base` Card can hold several `nested` Cards, for example to lay out a group
98+
of related sub-sections inside a single container.
99+
100+
```js
101+
---
102+
type: example
103+
---
104+
<Card variant="base" size="lg">
105+
<div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
106+
<Card variant="nested">
107+
<Heading level="h3" margin="0 0 x-small 0">
108+
Course settings
109+
</Heading>
110+
<Text variant="content">
111+
Control who can see this course and when it becomes available to
112+
students.
113+
</Text>
114+
</Card>
115+
<Card variant="nested">
116+
<Heading level="h3" margin="0 0 x-small 0">
117+
Grading
118+
</Heading>
119+
<Text variant="content">
120+
Choose the grading scheme and decide how final grades are calculated.
121+
</Text>
122+
</Card>
123+
<Card variant="nested">
124+
<Heading level="h3" margin="0 0 x-small 0">
125+
Notifications
126+
</Heading>
127+
<Text variant="content">
128+
Pick which course events should send an alert to enrolled users.
129+
</Text>
130+
</Card>
131+
</div>
132+
</Card>
133+
```
134+
135+
### Guidelines
136+
137+
```js
138+
---
139+
type: embed
140+
---
141+
<Guidelines>
142+
<Figure recommendation="yes" title="Do">
143+
<Figure.Item>
144+
Place a <code>nested</code> Card inside a <code>base</code> Card
145+
</Figure.Item>
146+
<Figure.Item>
147+
Place a <code>nested</code> Card on top of another surface, such as a
148+
Card, Modal, or utility panel (e.g. Tray, DrawerLayout)
149+
</Figure.Item>
150+
<Figure.Item>
151+
Size each <code>nested</code> Card independently, based on its own
152+
content — it doesn't need to match its parent{' '}
153+
<code>base</code> Card's <code>size</code>
154+
</Figure.Item>
155+
<Figure.Item>
156+
Give a row of <code>md</code>/<code>lg</code> <code>nested</code> Cards
157+
enough width to fit their minimum widths, or let them wrap, when
158+
placing several side by side
159+
</Figure.Item>
160+
</Figure>
161+
<Figure recommendation="no" title="Don't">
162+
<Figure.Item>
163+
Place a <code>base</code> Card inside another <code>base</code> Card
164+
</Figure.Item>
165+
<Figure.Item>
166+
Place a <code>nested</code> Card directly on the page background — it
167+
relies on a surface behind it for contrast, since it has no background
168+
color of its own
169+
</Figure.Item>
170+
</Figure>
171+
</Guidelines>
172+
```

0 commit comments

Comments
 (0)