Material Icons Usage Guide¶
A guide to using Material Design icons consistently throughout documentation
Overview¶
This guide establishes standards for using Material Design icons across our documentation to ensure visual consistency and improve user experience. By following these guidelines, we maintain a cohesive visual language throughout the project. Material icons provide visual cues that enhance readability and navigation while maintaining a professional appearance.
Icon Styling Classes¶
We've implemented standardized CSS classes to control icon appearance. Use these classes consistently when adding icons to documentation.
Size Classes¶
| Class | Size | Use Case |
|---|---|---|
.lg |
1.5rem | Large icons for navigation, section headers, and cards |
.md |
1.2rem | Medium icons for subheadings and inline emphasis |
.sm |
1.0rem | Small icons for inline text and compact lists |
Alignment Classes¶
| Class | Alignment | Use Case |
|---|---|---|
.middle |
Vertically centered | Default alignment for most icons |
.top |
Top-aligned | When aligning with first line of multi-line text |
.bottom |
Bottom-aligned | When aligning with last line of multi-line text |
Status Classes¶
| Class | Color | Use Case |
|---|---|---|
.success |
Green (#4caf50) | Positive outcomes, completed tasks, successful operations |
.warning |
Orange (#ff9800) | Warnings, partial completion, needs attention |
.error, .failure |
Red (#f44336) | Errors, failures, critical issues |
.info |
Blue (#2196f3) | Informational elements, neutral status |
Material Design Color Classes¶
For more specific color control, use the Material Design color palette classes:
.md-color--red
.md-color--pink
.md-color--purple
.md-color--deep-purple
.md-color--indigo
.md-color--blue
.md-color--light-blue
.md-color--cyan
.md-color--teal
.md-color--green
.md-color--light-green
.md-color--lime
.md-color--yellow
.md-color--amber
.md-color--orange
.md-color--deep-orange
.md-color--brown
.md-color--grey
.md-color--blue-grey
Usage Examples¶
Basic Icon Usage¶
Renders as: Information
Icons with Status Colors¶
:material-check-circle:{ .success } Completed
:material-alert-circle:{ .warning } Needs Attention
:material-close-circle:{ .error } Failed
:material-information:{ .info } Note
Renders as:
Completed Needs Attention Failed Note
Icons in Tables¶
| Status | Description |
|--------|-------------|
| :material-check-circle:{ .success } | Task completed successfully |
| :material-alert-circle:{ .warning } | Task needs attention |
| :material-close-circle:{ .error } | Task failed |
| Status | Description |
|---|---|
| Task completed successfully | |
| Task needs attention | |
| Task failed |
Icons in Navigation¶
For navigation items and cards, use the .lg size class with .middle alignment:
- :material-file-document:{ .lg .middle } **Documentation**
- :material-code-tags:{ .lg .middle } **Code Examples**
- :material-chart-bar:{ .lg .middle } **Analytics**
Renders as:
- Documentation
- Code Examples
- Analytics
Icons with Material Design Colors¶
:material-alert-circle:{ .md-color--red } Critical
:material-information:{ .md-color--blue } Information
:material-check-circle:{ .md-color--green } Success
Renders as:
Critical Information Success
Common Icon Sets¶
Status Icons¶
| Icon | Name | Usage | Recommended Classes |
|---|---|---|---|
check-circle |
Success, completion | .success |
|
alert-circle |
Warning, caution | .warning |
|
close-circle |
Error, failure | .error |
|
information |
Information, note | .info |
|
help-circle |
Help, question | .info |
|
progress-clock |
In progress | .warning |
|
check |
Completed item | .success |
|
close |
Failed item | .error |
Document Icons¶
| Icon | Name | Usage | Recommended Classes |
|---|---|---|---|
file-document |
General documents | .lg .middle for navigation |
|
file-document-outline |
Document outline/template | .lg .middle for navigation |
|
file-document-multiple |
Multiple documents | .lg .middle for navigation |
|
book-open-variant |
Documentation, guides | .lg .middle for navigation |
|
notebook |
Notes, journals | .lg .middle for navigation |
|
book-alphabet |
Glossary, dictionary | .lg .middle for navigation |
|
text-box-outline |
Content sections | Default size for headers |
Navigation Icons¶
| Icon | Name | Usage | Recommended Classes |
|---|---|---|---|
home |
Home page | .middle for links |
|
arrow-right |
Next, continue | .middle for links |
|
arrow-left |
Previous, back | .middle for links |
|
menu |
Menu, navigation | .middle for links |
|
link |
Links, references | .middle for links |
|
github |
GitHub links | .middle for links |
|
book |
Documentation links | .middle for links |
Development Icons¶
| Icon | Name | Usage | Recommended Classes |
|---|---|---|---|
code-tags |
Code, development | Default size for headers | |
git |
Git, version control | .lg .middle for navigation |
|
database |
Database, storage | Default size for headers | |
server |
Server, infrastructure | Default size for headers | |
language-python |
Python programming | Default size for headers | |
package |
Packages, dependencies | Default size for headers | |
docker |
Docker, containers | .lg .middle for navigation |
Process & Workflow Icons¶
| Icon | Name | Usage | Recommended Classes |
|---|---|---|---|
timeline-outline |
Process flows | Default size for headers | |
chart-timeline-variant |
Project timelines | Default size for headers | |
account-group |
Teams, stakeholders | .lg .middle for navigation |
|
target |
Goals, objectives | Default size for headers | |
lightbulb-outline |
Ideas, lessons learned | Default size for headers | |
chart-bar |
Metrics, analytics | Default size for headers |
Best Practices¶
- Consistency: Use the same icon for the same concept throughout documentation
- Simplicity: Don't overuse icons; they should enhance, not distract
- Accessibility: Icons should complement text, not replace it
- Sizing: Use appropriate size classes based on context
- Color: Use status colors consistently to convey meaning
- Spacing: Maintain consistent spacing between icons and text
- Hierarchy: Use icon size to establish visual hierarchy
Consistency Patterns¶
To maintain visual consistency across documentation, follow these standardized patterns for common use cases:
Section Headers¶
For all section headers (h2, h3, h4), use the icon without size class (default size):
## :material-code-tags: Development Guide
### :material-information-outline: Important Notes
#### :material-pencil-outline: Implementation Details
Navigation Links¶
For navigation links and cards, always use the .lg size with .middle alignment:
- :material-file-document:{ .lg .middle } **Documentation**
- :material-code-tags:{ .lg .middle } **Code Examples**
Status Indicators¶
For status indicators, always use the appropriate status class:
:material-check-circle:{ .success } Completed
:material-alert-circle:{ .warning } In Progress
:material-close-circle:{ .error } Failed
Inline Text Icons¶
For icons within paragraph text, use the .md size with .middle alignment:
Icon Links¶
For icon links, use the .middle alignment without size class:
Implementation¶
The styling for these icons is defined in docs/static/stylesheets/material-icons.css and is automatically included in the MkDocs build. To use these styles, simply add the appropriate classes to your Material icons in markdown files.