Skip to content

Commit cd1adf7

Browse files
Rajesh-Nagarajan-11Rajesh-Nagarajan-11
authored
Merge pull request #7582 from abhay1999/add-card-component-docs
[Sistent] Add Card component to the sistent components page
2 parents d8ce95d + c4f87f9 commit cd1adf7

3 files changed

Lines changed: 364 additions & 0 deletions

File tree

‎src/collections/sistent/components/card/code.mdx‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
---
2+
title: Card Code
3+
component: card
4+
description: A card is a contained surface that groups related information and actions about a single subject, making content easy to scan and interact with.
5+
---
6+
7+
import { Card, Button } from "@sistent/sistent";
8+
9+
The Card component wraps MUI's Card and works with Sistent's theming out of the box. Here are the most common usage patterns.
10+
11+
<a id="Basic Card">
12+
<h2>Basic Card</h2>
13+
</a>
14+
15+
A basic card with some content inside. By default it uses the elevated style with a subtle shadow.
16+
17+
<div className="showcase">
18+
<div className="items">
19+
<ThemeWrapper>
20+
<div style={{ display: 'flex', justifyContent: 'center', padding: '16px' }}>
21+
<Card style={{ width: 300, padding: '16px' }}>
22+
Simple card content
23+
</Card>
24+
</div>
25+
</ThemeWrapper>
26+
</div>
27+
<CodeBlock name="basic-card" collapsible code={`<SistentThemeProvider initialMode={isDark ? "dark" : "light"}>
28+
<Card style={{ width: 300, padding: "16px" }}>
29+
Simple card content
30+
</Card>
31+
</SistentThemeProvider>`} />
32+
</div>
33+
34+
<a id="Outlined Card">
35+
<h2>Outlined Card</h2>
36+
</a>
37+
38+
Use `variant="outlined"` to get a card with a border instead of a shadow. Useful when the background is already elevated or when you want a lighter visual style.
39+
40+
<div className="showcase">
41+
<div className="items">
42+
<ThemeWrapper>
43+
<div style={{ display: 'flex', justifyContent: 'center', padding: '16px' }}>
44+
<Card variant="outlined" style={{ width: 300, padding: '16px' }}>
45+
Outlined card content
46+
</Card>
47+
</div>
48+
</ThemeWrapper>
49+
</div>
50+
<CodeBlock name="outlined-card" collapsible code={`<SistentThemeProvider initialMode={isDark ? "dark" : "light"}>
51+
<Card variant="outlined" style={{ width: 300, padding: "16px" }}>
52+
Outlined card content
53+
</Card>
54+
</SistentThemeProvider>`} />
55+
</div>
56+
57+
<a id="Elevation">
58+
<h2>Elevation</h2>
59+
</a>
60+
61+
The `elevation` prop controls shadow depth. Values go from 0 (flat) to 24 (maximum depth). Most cards in practice sit between 1 and 8.
62+
63+
<div className="showcase">
64+
<div className="items">
65+
<ThemeWrapper>
66+
<div style={{ display: 'flex', flexDirection: 'column', gap: '12px', padding: '16px' }}>
67+
<Card elevation={1} style={{ padding: '16px' }}>Elevation 1</Card>
68+
<Card elevation={4} style={{ padding: '16px' }}>Elevation 4</Card>
69+
<Card elevation={8} style={{ padding: '16px' }}>Elevation 8</Card>
70+
</div>
71+
</ThemeWrapper>
72+
</div>
73+
<CodeBlock name="card-elevation" collapsible code={`<SistentThemeProvider initialMode={isDark ? "dark" : "light"}>
74+
<Card elevation={1} style={{ padding: "16px" }}>Elevation 1</Card>
75+
<Card elevation={4} style={{ padding: "16px" }}>Elevation 4</Card>
76+
<Card elevation={8} style={{ padding: "16px" }}>Elevation 8</Card>
77+
</SistentThemeProvider>`} />
78+
</div>
79+
80+
<a id="Square Corners">
81+
<h2>Square Corners</h2>
82+
</a>
83+
84+
Cards have rounded corners by default. Set `square` to `true` to remove the rounding for a more geometric look.
85+
86+
<div className="showcase">
87+
<div className="items">
88+
<ThemeWrapper>
89+
<div style={{ display: 'flex', gap: '16px', justifyContent: 'center', padding: '16px' }}>
90+
<Card style={{ width: 200, padding: '16px' }}>Rounded</Card>
91+
<Card square style={{ width: 200, padding: '16px' }}>Square</Card>
92+
</div>
93+
</ThemeWrapper>
94+
</div>
95+
<CodeBlock name="card-corners" collapsible code={`<SistentThemeProvider initialMode={isDark ? "dark" : "light"}>
96+
<Card style={{ width: 200, padding: "16px" }}>Rounded</Card>
97+
<Card square style={{ width: 200, padding: "16px" }}>Square</Card>
98+
</SistentThemeProvider>`} />
99+
</div>
100+
101+
<a id="Clickable Card">
102+
<h2>Clickable Card</h2>
103+
</a>
104+
105+
To make the entire card interactive, add an `onClick` handler and update the cursor style. This pattern is common in grid layouts where each card is a navigation target.
106+
107+
<div className="showcase">
108+
<div className="items">
109+
<ThemeWrapper>
110+
<div style={{ display: 'flex', justifyContent: 'center', padding: '16px' }}>
111+
<Card
112+
style={{ width: 300, padding: '16px', cursor: 'pointer' }}
113+
onClick={() => alert('Card clicked')}
114+
>
115+
Click anywhere on this card
116+
</Card>
117+
</div>
118+
</ThemeWrapper>
119+
</div>
120+
<CodeBlock name="clickable-card" collapsible code={`<SistentThemeProvider initialMode={isDark ? "dark" : "light"}>
121+
<Card
122+
style={{ width: 300, padding: "16px", cursor: "pointer" }}
123+
onClick={() => console.log("Card clicked")}
124+
>
125+
Click anywhere on this card
126+
</Card>
127+
</SistentThemeProvider>`} />
128+
</div>
129+
130+
<a id="Card with Header and Actions">
131+
<h2>Card with Header and Actions</h2>
132+
</a>
133+
134+
A common real-world pattern — a card with a title, a short description, and action buttons at the bottom.
135+
136+
<div className="showcase">
137+
<div className="items">
138+
<ThemeWrapper>
139+
<div style={{ display: 'flex', justifyContent: 'center', padding: '16px' }}>
140+
<Card style={{ width: 300 }}>
141+
<div style={{ padding: '16px' }}>
142+
<h3 style={{ margin: '0 0 8px' }}>Card Title</h3>
143+
<p style={{ margin: 0, color: 'gray' }}>A short description about what this card represents and why it matters.</p>
144+
</div>
145+
<div style={{ padding: '8px 16px 16px', display: 'flex', gap: '8px' }}>
146+
<Button variant="contained" size="small">Action</Button>
147+
<Button variant="outlined" size="small">Cancel</Button>
148+
</div>
149+
</Card>
150+
</div>
151+
</ThemeWrapper>
152+
</div>
153+
<CodeBlock name="card-with-actions" collapsible code={`<SistentThemeProvider initialMode={isDark ? "dark" : "light"}>
154+
<Card style={{ width: 300 }}>
155+
<div style={{ padding: "16px" }}>
156+
<h3 style={{ margin: "0 0 8px" }}>Card Title</h3>
157+
<p style={{ margin: 0, color: "gray" }}>
158+
A short description about what this card represents.
159+
</p>
160+
</div>
161+
<div style={{ padding: "8px 16px 16px", display: "flex", gap: "8px" }}>
162+
<Button variant="contained" size="small">Action</Button>
163+
<Button variant="outlined" size="small">Cancel</Button>
164+
</div>
165+
</Card>
166+
</SistentThemeProvider>`} />
167+
</div>

‎src/collections/sistent/components/card/guidance.mdx‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
title: Card Guidance
3+
component: card
4+
description: A card is a contained surface that groups related information and actions about a single subject, making content easy to scan and interact with.
5+
---
6+
7+
import { Card } from "@sistent/sistent";
8+
9+
Cards work best when they follow a consistent structure and are used intentionally. Here's how to get the most out of them.
10+
11+
<a id="When to Use">
12+
<h2>When to Use</h2>
13+
</a>
14+
15+
Cards are a great fit when you're presenting a collection of items that are related but independent — things like search results, product listings, user profiles, or dashboard widgets. The contained surface makes it easy for users to scan many items at once without losing track of where one ends and another begins.
16+
17+
<h3>Use cards when</h3>
18+
19+
- You have multiple items of the same type to display side by side
20+
- Each item has its own set of actions (like "Edit", "Delete", or "View")
21+
- The content can be summarized — cards are not meant to show full detail
22+
- You want to let users quickly identify which item they want before drilling in
23+
24+
<h3>Avoid cards when</h3>
25+
26+
- You only have a single piece of content — a card adds unnecessary structure here
27+
- The content is tabular — a table will do a better job showing relationships between rows
28+
- The layout is purely linear — a list or a stack of sections is simpler and more readable
29+
30+
<a id="Content Structure">
31+
<h2>Content Structure</h2>
32+
</a>
33+
34+
Cards work best with a predictable internal layout. When every card in a set follows the same structure, users can scan faster and actions are easier to find.
35+
36+
<h3>Keep it focused</h3>
37+
38+
A card should cover one subject. If you find yourself fitting two unrelated things into a single card, split them into two. A focused card is easier to scan and less likely to confuse.
39+
40+
<h3>Prioritize the header</h3>
41+
42+
The most important information — the title, name, or main identifier — should be at the top. Users scan in F-patterns; if the key info is buried, they'll miss it. Secondary details like descriptions or metadata can follow below.
43+
44+
<h3>Limit the number of actions</h3>
45+
46+
Cards shouldn't try to do too many things at once. One to two actions per card is a good rule of thumb. If you have more, consider whether some of those actions belong on a detail page instead.
47+
48+
<a id="Hierarchy">
49+
<h2>Hierarchy</h2>
50+
</a>
51+
52+
When multiple card types appear in the same layout, their visual weight should reflect their importance. Use elevation and variant choices deliberately to guide the user's eye.
53+
54+
<h3>Elevated cards for primary content</h3>
55+
56+
If cards are the main content on a page, use the default elevated style. The shadow helps them stand out from the background and from each other.
57+
58+
<h3>Outlined cards for secondary content</h3>
59+
60+
Outlined cards are a better fit for supplementary content, sidebars, or contexts where the background is already elevated. They're visually lighter and won't compete with the primary content.
61+
62+
<a id="Interactivity">
63+
<h2>Interactivity</h2>
64+
</a>
65+
66+
Whether or not a card is clickable should be clear from the visual treatment alone — don't make users guess.
67+
68+
<h3>Clickable cards</h3>
69+
70+
If the entire card is a navigation target, make sure there's a visible hover state. A subtle background color change or shadow shift is enough. The cursor should switch to a pointer on hover.
71+
72+
<h3>Cards with actions</h3>
73+
74+
If a card has specific action buttons (rather than a full-card click), those should be visually distinct and located in a consistent spot — usually the bottom of the card. Don't mix full-card clicks with inline buttons, as this creates conflicting affordances.
75+
76+
<h3>Non-interactive cards</h3>
77+
78+
Remove any hover effects from purely informational cards. No pointer cursor, no shadow change on hover. This keeps the visual language consistent and prevents users from clicking on things that don't go anywhere.
79+
80+
<a id="Accessibility">
81+
<h2>Accessibility</h2>
82+
</a>
83+
84+
Cards should be accessible without requiring visual context to understand their purpose.
85+
86+
- If a card is clickable, make sure it has a meaningful `aria-label` or that the visible text is descriptive enough to serve as the accessible name
87+
- Avoid using only color or icons to convey the card's purpose — pair them with a visible text label
88+
- Ensure sufficient color contrast between the card surface and its contents
89+
- Focus outlines should be visible on all interactive elements within a card
90+
- If cards reorder or update dynamically, use appropriate ARIA live regions so screen reader users are notified of changes

‎src/collections/sistent/components/card/index.mdx‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
---
2+
name: "Card"
3+
title: Card
4+
published: true
5+
component: card
6+
description: A card is a contained surface that groups related information and actions about a single subject, making content easy to scan and interact with.
7+
---
8+
9+
import { Card } from "@sistent/sistent";
10+
11+
Cards are versatile containers that bring together content and actions around a single topic. They give users a clean, scannable way to browse and interact with information — whether that's a product, a profile, a post, or anything in between. Cards can live in grids, lists, or standalone layouts, and they scale well across screen sizes.
12+
13+
<a id="Types">
14+
<h2>Types</h2>
15+
</a>
16+
17+
Cards come in a few configurations depending on how much visual weight and interactivity you need. Choosing the right one helps keep the interface consistent and easy to navigate.
18+
19+
<h3>Elevated</h3>
20+
21+
The default card type. It uses a drop shadow to sit above the background, creating a sense of depth. This is the most common type and works well for content-heavy layouts where you need clear separation between items.
22+
23+
<Row className="image-container">
24+
<ThemeWrapper>
25+
<div style={{ display: 'flex', justifyContent: 'center', width: '100%', padding: '16px' }}>
26+
<Card style={{ width: 280, padding: '16px' }}>
27+
<p style={{ margin: 0 }}>Elevated Card</p>
28+
</Card>
29+
</div>
30+
</ThemeWrapper>
31+
</Row>
32+
33+
<h3>Outlined</h3>
34+
35+
An outlined card drops the shadow and uses a border instead. It's a good pick when you want a lighter look, or when the background is already elevated and adding more depth would feel cluttered.
36+
37+
<Row className="image-container">
38+
<ThemeWrapper>
39+
<div style={{ display: 'flex', justifyContent: 'center', width: '100%', padding: '16px' }}>
40+
<Card variant="outlined" style={{ width: 280, padding: '16px' }}>
41+
<p style={{ margin: 0 }}>Outlined Card</p>
42+
</Card>
43+
</div>
44+
</ThemeWrapper>
45+
</Row>
46+
47+
<a id="Elevation">
48+
<h2>Elevation</h2>
49+
</a>
50+
51+
The `elevation` prop lets you control how prominent a card feels. Values range from 0 (flat, no shadow) all the way up to 24 (maximum depth). Most cards in practice sit between 1 and 8 — high enough to stand out without feeling heavy.
52+
53+
<Row className="image-container">
54+
<ThemeWrapper>
55+
<div style={{ display: 'flex', flexDirection: 'column', gap: '12px', padding: '16px', width: '100%' }}>
56+
<Card elevation={1} style={{ padding: '16px' }}>Elevation 1 — subtle</Card>
57+
<Card elevation={4} style={{ padding: '16px' }}>Elevation 4 — moderate</Card>
58+
<Card elevation={8} style={{ padding: '16px' }}>Elevation 8 — prominent</Card>
59+
</div>
60+
</ThemeWrapper>
61+
</Row>
62+
63+
<a id="Interactivity">
64+
<h2>Interactivity</h2>
65+
</a>
66+
67+
Cards can be made clickable by wrapping them in an action area or by setting the `onClick` handler directly. When a card is interactive, it should have a clear hover and focus state so users know it's actionable.
68+
69+
<h3>Clickable Card</h3>
70+
71+
Use a clickable card when the entire surface should trigger a navigation or action. This is common in grids where each card represents a destination — like a product page or a settings section.
72+
73+
<Row className="image-container">
74+
<ThemeWrapper>
75+
<div style={{ display: 'flex', justifyContent: 'center', width: '100%', padding: '16px' }}>
76+
<Card
77+
style={{ width: 280, padding: '16px', cursor: 'pointer' }}
78+
onClick={() => {}}
79+
>
80+
<p style={{ margin: 0 }}>Click me</p>
81+
</Card>
82+
</div>
83+
</ThemeWrapper>
84+
</Row>
85+
86+
<h3>Non-interactive Card</h3>
87+
88+
Not every card needs to be clickable. When a card is purely informational — like a stats panel or a summary block — it should not have hover effects or pointer cursors, since those signal interactivity that doesn't exist.
89+
90+
<a id="Raised Corners">
91+
<h2>Corners</h2>
92+
</a>
93+
94+
By default, cards have rounded corners. If you need a more geometric, grid-aligned look, you can use the `square` prop to remove the rounding entirely.
95+
96+
<Row className="image-container">
97+
<ThemeWrapper>
98+
<div style={{ display: 'flex', gap: '16px', justifyContent: 'center', padding: '16px' }}>
99+
<Card style={{ width: 200, padding: '16px' }}>
100+
<p style={{ margin: 0 }}>Rounded (default)</p>
101+
</Card>
102+
<Card square style={{ width: 200, padding: '16px' }}>
103+
<p style={{ margin: 0 }}>Square corners</p>
104+
</Card>
105+
</div>
106+
</ThemeWrapper>
107+
</Row>

0 commit comments

Comments
 (0)