Skip to content

Commit bac92a8

Browse files
naikmubashirnaikmubashir
committed
docs(sistent): add IconButton usage guidance and best practices
Signed-off-by: Naik Mubashir <naikmubashir095@gmail.com>
1 parent aa1549e commit bac92a8

1 file changed

Lines changed: 340 additions & 0 deletions

File tree

  • src/sections/Projects/Sistent/components/iconbutton

‎src/sections/Projects/Sistent/components/iconbutton/guidance.js‎

Lines changed: 340 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,340 @@
1+
import React from "react";
2+
import { navigate } from "gatsby";
3+
import { useLocation } from "@reach/router";
4+
import { Row } from "../../../../../reusecore/Layout";
5+
import { IconButton, SistentThemeProvider } from "@sistent/sistent";
6+
import { SistentLayout } from "../../sistent-layout";
7+
import { FaCheck } from "@react-icons/all-files/fa/FaCheck";
8+
import { FaTimes } from "@react-icons/all-files/fa/FaTimes";
9+
import { FaHeart } from "@react-icons/all-files/fa/FaHeart";
10+
import { FaShare } from "@react-icons/all-files/fa/FaShare";
11+
12+
import TabButton from "../../../../../reusecore/Button";
13+
import { useStyledDarkMode } from "../../../../../theme/app/useStyledDarkMode";
14+
15+
const IconButtonGuidance = () => {
16+
const location = useLocation();
17+
const { isDark } = useStyledDarkMode();
18+
19+
return (
20+
<SistentLayout title="IconButton">
21+
<div className="content">
22+
<a id="Identity">
23+
<h2>IconButton</h2>
24+
</a>
25+
<p>
26+
IconButton provides an interactive button component that displays only
27+
an icon, ideal for compact UIs where space is limited and actions are
28+
easily recognizable through iconography.
29+
</p>
30+
<div className="filterBtns">
31+
<TabButton
32+
className={
33+
location.pathname === "/projects/sistent/components/iconbutton"
34+
? "active"
35+
: ""
36+
}
37+
onClick={() => navigate("/projects/sistent/components/iconbutton")}
38+
title="Overview"
39+
/>
40+
<TabButton
41+
className={
42+
location.pathname ===
43+
"/projects/sistent/components/iconbutton/guidance"
44+
? "active"
45+
: ""
46+
}
47+
onClick={() =>
48+
navigate("/projects/sistent/components/iconbutton/guidance")
49+
}
50+
title="Guidance"
51+
/>
52+
<TabButton
53+
className={
54+
location.pathname ===
55+
"/projects/sistent/components/iconbutton/code"
56+
? "active"
57+
: ""
58+
}
59+
onClick={() =>
60+
navigate("/projects/sistent/components/iconbutton/code")
61+
}
62+
title="Code"
63+
/>
64+
</div>
65+
<div className="main-content">
66+
<a id="Usage Guidelines">
67+
<h2>Usage Guidelines</h2>
68+
</a>
69+
<p>
70+
IconButtons should be used when the action can be clearly
71+
communicated through iconography alone. They're perfect for common
72+
actions that users can easily recognize without accompanying text.
73+
</p>
74+
75+
<a id="When to Use">
76+
<h3>When to Use IconButtons</h3>
77+
</a>
78+
<ul>
79+
<li>
80+
<strong>Space-constrained interfaces:</strong> Toolbars, headers,
81+
and compact layouts
82+
</li>
83+
<li>
84+
<strong>Secondary actions:</strong> Edit, delete, share, or
85+
favorite actions
86+
</li>
87+
<li>
88+
<strong>Repetitive actions:</strong> Actions that appear multiple
89+
times in lists or tables
90+
</li>
91+
<li>
92+
<strong>Universal actions:</strong> Widely recognized actions like
93+
play, pause, or close
94+
</li>
95+
<li>
96+
<strong>Quick actions:</strong> Actions that don't require
97+
additional context
98+
</li>
99+
</ul>
100+
101+
<Row $Hcenter className="image-container">
102+
<SistentThemeProvider initialMode={isDark ? "dark" : "light"}>
103+
<IconButton aria-label="favorite" color="error">
104+
<FaHeart />
105+
</IconButton>
106+
<IconButton aria-label="share" color="primary">
107+
<FaShare />
108+
</IconButton>
109+
</SistentThemeProvider>
110+
</Row>
111+
112+
<a id="When to Avoid">
113+
<h3>When to Avoid IconButtons</h3>
114+
</a>
115+
<ul>
116+
<li>
117+
<strong>Primary actions:</strong> Use regular buttons with text
118+
for main CTAs
119+
</li>
120+
<li>
121+
<strong>Complex actions:</strong> Actions that require explanation
122+
or context
123+
</li>
124+
<li>
125+
<strong>Ambiguous icons:</strong> When the icon meaning isn't
126+
universally clear
127+
</li>
128+
<li>
129+
<strong>First-time user flows:</strong> Where users need guidance
130+
and clarity
131+
</li>
132+
<li>
133+
<strong>Critical destructive actions:</strong> Important actions
134+
like "Delete Account"
135+
</li>
136+
</ul>
137+
138+
<a id="Accessibility Best Practices">
139+
<h2>Accessibility Best Practices</h2>
140+
</a>
141+
142+
<h3>Required Attributes</h3>
143+
<ul>
144+
<li>
145+
<strong>aria-label:</strong> Always provide descriptive labels
146+
</li>
147+
<li>
148+
<strong>Meaningful descriptions:</strong> Use specific,
149+
action-oriented labels
150+
</li>
151+
<li>
152+
<strong>Consistent labeling:</strong> Use the same label for the
153+
same action across your app
154+
</li>
155+
</ul>
156+
157+
<h3>Touch and Click Targets</h3>
158+
<ul>
159+
<li>
160+
<strong>Minimum size:</strong> Ensure at least 44px touch targets
161+
for mobile
162+
</li>
163+
<li>
164+
<strong>Adequate spacing:</strong> Provide sufficient space
165+
between adjacent IconButtons
166+
</li>
167+
<li>
168+
<strong>Visual feedback:</strong> Clear hover and focus states
169+
</li>
170+
</ul>
171+
172+
<a id="Design Guidelines">
173+
<h2>Design Guidelines</h2>
174+
</a>
175+
176+
<h3>Icon Selection</h3>
177+
<ul>
178+
<li>
179+
<strong>Recognizable icons:</strong> Use widely understood icons
180+
from established icon libraries
181+
</li>
182+
<li>
183+
<strong>Consistent style:</strong> Maintain visual consistency
184+
across all icons
185+
</li>
186+
<li>
187+
<strong>Appropriate weight:</strong> Match icon weight to your
188+
overall design
189+
</li>
190+
<li>
191+
<strong>Scalable icons:</strong> Use vector icons that scale
192+
clearly at different sizes
193+
</li>
194+
</ul>
195+
196+
<h3>Visual States</h3>
197+
<p>
198+
IconButtons should provide clear visual feedback for different
199+
interaction states:
200+
</p>
201+
<ul>
202+
<li>
203+
<strong>Default:</strong> Clear, recognizable icon with
204+
appropriate contrast
205+
</li>
206+
<li>
207+
<strong>Hover:</strong> Subtle background or color change to
208+
indicate interactivity
209+
</li>
210+
<li>
211+
<strong>Focus:</strong> Clear focus indicator for keyboard
212+
navigation
213+
</li>
214+
<li>
215+
<strong>Active:</strong> Pressed state feedback for better user
216+
experience
217+
</li>
218+
<li>
219+
<strong>Disabled:</strong> Reduced opacity or different styling
220+
for inactive states
221+
</li>
222+
</ul>
223+
224+
<a id="Layout and Spacing">
225+
<h2>Layout and Spacing</h2>
226+
</a>
227+
228+
<h3>Spacing Guidelines</h3>
229+
<ul>
230+
<li>
231+
<strong>Between IconButtons:</strong> Minimum 8px spacing to
232+
prevent accidental touches
233+
</li>
234+
<li>
235+
<strong>In toolbars:</strong> Consistent spacing aligned with grid
236+
system
237+
</li>
238+
<li>
239+
<strong>With other elements:</strong> Align with text baselines
240+
and other UI elements
241+
</li>
242+
</ul>
243+
244+
<h3>Grouping</h3>
245+
<p>When grouping IconButtons, consider:</p>
246+
<ul>
247+
<li>
248+
<strong>Related actions:</strong> Group similar or related actions
249+
together
250+
</li>
251+
<li>
252+
<strong>Visual separation:</strong> Use dividers or spacing to
253+
separate different action groups
254+
</li>
255+
<li>
256+
<strong>Logical order:</strong> Arrange actions in a logical,
257+
predictable order
258+
</li>
259+
</ul>
260+
261+
<Row $Hcenter className="image-container">
262+
<SistentThemeProvider initialMode={isDark ? "dark" : "light"}>
263+
<div
264+
style={{ display: "flex", gap: "16px", alignItems: "center" }}
265+
>
266+
<IconButton aria-label="approve" color="success">
267+
<FaCheck />
268+
</IconButton>
269+
<IconButton aria-label="reject" color="error">
270+
<FaTimes />
271+
</IconButton>
272+
</div>
273+
</SistentThemeProvider>
274+
</Row>
275+
276+
<a id="Interaction Patterns">
277+
<h2>Interaction Patterns</h2>
278+
</a>
279+
280+
<h3>Toggle States</h3>
281+
<p>
282+
IconButtons can represent toggle states (like favorite/unfavorite)
283+
by:
284+
</p>
285+
<ul>
286+
<li>
287+
<strong>Color changes:</strong> Different colors for
288+
active/inactive states
289+
</li>
290+
<li>
291+
<strong>Icon variants:</strong> Filled vs. outlined icons
292+
</li>
293+
<li>
294+
<strong>Visual feedback:</strong> Clear indication of current
295+
state
296+
</li>
297+
</ul>
298+
299+
<h3>Loading States</h3>
300+
<p>For actions that take time to complete:</p>
301+
<ul>
302+
<li>
303+
<strong>Disable during processing:</strong> Prevent multiple
304+
submissions
305+
</li>
306+
<li>
307+
<strong>Loading indicators:</strong> Show progress for longer
308+
operations
309+
</li>
310+
<li>
311+
<strong>Feedback messages:</strong> Confirm completion or show
312+
errors
313+
</li>
314+
</ul>
315+
316+
<a id="Common Patterns">
317+
<h2>Common Patterns</h2>
318+
</a>
319+
320+
<h3>Toolbar Actions</h3>
321+
<p>
322+
Edit, share, delete, and other common actions in toolbars and
323+
headers.
324+
</p>
325+
326+
<h3>List Item Actions</h3>
327+
<p>Quick actions for items in lists, tables, or cards.</p>
328+
329+
<h3>Media Controls</h3>
330+
<p>Play, pause, skip, and volume controls for media players.</p>
331+
332+
<h3>Navigation</h3>
333+
<p>Back, forward, close, and menu toggle actions.</p>
334+
</div>
335+
</div>
336+
</SistentLayout>
337+
);
338+
};
339+
340+
export default IconButtonGuidance;

0 commit comments

Comments
 (0)