Acme Design System

Component Usage Guide

When and how to use every component in the Acme Design System. The canonical reference for designers and developers.

This guide defines when and how to use each component in the Acme Design System. Follow these guidelines to ensure consistency across all product surfaces.

ℹ
Golden rule: Always use the system component. Never build custom UI for something the system already solves. If you need something new, propose it as a design system addition.

Quick Reference

ComponentVariantsSizesStates
Alert Info · Success · Warning · Error Full width With / without dismiss
Avatar 6 colors × 2 shades (Light/Dark) SM 24px · MD 32px · LG 40px N/A
Badge Default (dot) · No-dot · Pill Auto N/A
Button Primary · Secondary · Ghost · Danger · Ghost-Danger SM · MD · LG Default · Hover · Active · Focus · Disabled
Card Default · Hover Fixed width, auto height Default · Hover
Checkbox Standalone · With Label · With Description · Group 18×18px fixed Default · Checked · Indeterminate · Disabled
CountBadge 6 colors × 2 shades Auto N/A
DataTable 5 density variants + Loading / Empty / FilterActive Full width Default · Loading · Empty · FilterActive
Dropdown Simple · With Icons · Grouped · FilterSelect · SortSelect Auto Default · Open · Hover
FormLayout Single column · Two column · Block Full width N/A
Input Text · Select · Textarea MD (fixed) Default · Hover · Focus · Error · Disabled
Modal Confirmation · Form · Destructive 480px wide Open · Closed
Navbar Light · Dark Full width · 52px height Default
Radio Vertical · Horizontal · Card 18×18px fixed Default · Selected · Disabled
StatCard Default · Trend Up · Trend Down Fixed width N/A
TabBar Light · Dark · Pill · Counts Hug width Default · Hover · Active · Disabled
Toggle Default · With Label 32×18px fixed On · Off · Disabled

Component Details

Alert

When to use
Use for page-level feedback messages. Always place at the top of content. Use correct semantic color.
Don'ts
Don't use Alert for inline field validation — use Input error state.
Figma properties
Type, Dismissible
CSS class
.alert .alert-info / .alert-success / .alert-warning / .alert-error

Avatar

When to use
Use to represent a user or entity. Match shade to surface: Light on dark bg, Dark on light bg.
Don'ts
Don't use Avatar as decorative element without user context.
Figma properties
Size, Shade, Color
CSS class
.avatar .avatar-md .avatar-brand-dark etc.

Badge

When to use
Use to label or categorize items. Match color to semantic meaning: Brand=active, Success=complete, Error=failed, Warning=attention, Neutral=inactive.
Don'ts
Don't use more than 3 badge colors in the same view.
Figma properties
Color, Style
CSS class
.badge .badge-brand / .badge-success / .badge-error etc.

Button

When to use
Use Primary for the single most important action per view. Secondary for supporting actions. Ghost for low-emphasis tertiary actions. Danger for destructive irreversible actions.
Don'ts
Don't use more than one Primary per section. Don't use Danger for non-destructive actions. Don't disable without explaining why.
Figma properties
Type, State, Size, Icon
CSS class
.btn .btn-primary / .btn-secondary / .btn-ghost / .btn-danger

Card

When to use
Use to group related content. Hover state is automatic on interactive cards.
Don'ts
Don't nest cards inside cards.
Figma properties
Shadow
CSS class
.card

Checkbox

When to use
Use for multi-select options. Use groups for related choices.
Don'ts
Don't use for single binary choices — Toggle is more appropriate.
Figma properties
State, Label, Description
CSS class
.checkbox

CountBadge

When to use
Use inside TabBar=Counts or anywhere a numeric count needs semantic color. Palette matches Avatar.
Don'ts
Don't use for non-numeric content.
Figma properties
Shade, Color, Count
CSS class
.badge (pill)

DataTable

When to use
Use for structured tabular data with sorting and filtering. Choose density by data complexity.
Don'ts
Don't use DataTable for fewer than 3 columns — use a list instead.
Figma properties
Density, State
CSS class
.data-table

FormLayout

When to use
Use to structure input forms consistently. Two-column for short related fields, single for long inputs.
Don'ts
Don't mix column counts randomly within the same form.
Figma properties
Layout
CSS class
.form-layout .cols-2

Input

When to use
Use for any text entry. Add a label above and helper text below. Use Error state with a message on validation failure.
Don'ts
Don't use placeholder as a label substitute. Don't show error state without an error message.
Figma properties
State, Label, Placeholder, HelperText, ErrorText
CSS class
.input / .input.is-error

Radio

When to use
Use when exactly one option from a set must be selected. Always show all options.
Don'ts
Don't use for more than 6 options — use a Select dropdown instead.
Figma properties
State, Label, Direction
CSS class
.radio

StatCard

When to use
Use on dashboards to surface key metrics. Always pair a number with a label and trend indicator.
Don'ts
Don't use more than 6 stat cards in a row.
Figma properties
Value, Label, Trend
CSS class
.stat-card

TabBar

When to use
Light for content sections. Dark on brand surfaces. Pill for binary choices. Counts when status numbers matter.
Don'ts
Don't use more than 6 tabs.
Figma properties
Style, Theme, State, Count
CSS class
.tabs

Toggle

When to use
Use for immediate binary settings that take effect without a save action. Prefer over checkbox for system settings.
Don'ts
Don't use Toggle when the action needs a confirmation step.
Figma properties
State, Label
CSS class
.toggle