JM Family Design System

Anti-Patterns

Common design and implementation mistakes, paired with the correct alternative and the principle being violated. Use this catalog as a reviewer's reference, a self-check before shipping, and a teaching artifact.

Each entry shows the wrong way, explains why it’s wrong, and gives you the right alternative, with links to the relevant tokens, components, and design principles. Filter by category or severity, or search by keyword.

The wrong wayThe pattern we don’t ship — shown so reviewers can recognize it.
The right wayThe recommended alternative, with the rationale that justifies it.

Color & Theming

2

Anti-patterns related to color choices, token usage, theme support, and brand application.

Hardcoded hex values in component code

high

Embedding raw hex colors directly into CSS or component code bypasses theme support and brand consistency.

colortokenstheming

Using global color tokens directly in component code

high

Referencing `color.teal.500` in components instead of `color.text.brand` collapses the semantic layer and locks components to specific palette values.

colortokenssemantic-tier

Typography

1

Anti-patterns related to type sizing, weight, hierarchy, and the typography token scale.

Hardcoded font sizes instead of typography tokens

medium

Using raw pixel or rem values for font sizes breaks the type scale and creates visual inconsistency across pages.

typographytokenstype-scale

Spacing & Layout

1

Anti-patterns related to margin, padding, alignment, and the spacing token scale.

Pixel-precise spacing outside the token scale

medium

Using arbitrary spacing values like `13px` or `padding: 22px 14px` breaks the 4px base unit and creates inconsistent visual rhythm.

spacingtokensrhythm

Components

2

Anti-patterns related to using design system components in the wrong context or in the wrong way.

Disabling a button without explaining why

high

A greyed-out "Submit" button with no hint about what's missing forces users to guess what they did wrong.

formsbuttonsfeedback

Using a Toast for critical errors that require action

high

Toasts auto-dismiss. If the user must take action, or risks losing work, a toast hides the error before they can read it.

feedbackerrorscomponent-selection

Interaction & States

1

Anti-patterns related to hover, focus, active, disabled, and other interaction states.

Removing the focus outline without replacing it

high

Stripping `outline: none` without a visible replacement makes the interface unusable for keyboard users.

focuskeyboardaccessibilityWCAG-2.4.7

Accessibility

1

Anti-patterns that create barriers for users with disabilities. Often overlap other categories.

Communicating state with color alone

high

Marking errors red and successes green with no other cue fails users with color vision deficiency, and screen reader users entirely.

accessibilitycolorWCAG-1.4.1icons

Content & Voice

2

Anti-patterns related to interface copy, error messages, voice, tone, and terminology.

Cute error messages for failures that need real action

medium

Whimsical copy on consequential errors trivializes the user's problem and hides what they should do next.

voicetoneerrorscopy

Generic empty-state copy that says nothing

medium

Empty states that say only "No data" or "No items found" leave users unsure what belongs there or what to do next.

voiceempty-statecopypatterns

Motion

3

Anti-patterns related to animation, transitions, and motion design.

Animations that ignore prefers-reduced-motion

high

JavaScript-driven animations that don't check the user's reduced-motion preference will fire for users who have explicitly asked their device to hold the motion.

accessibilitymotionWCAG-2.3.3vestibular

Hardcoded duration and easing in component code

high

Writing `transition: opacity 250ms ease-in-out` instead of using motion tokens bypasses the system and creates animations that visually disagree across the product.

motiontokensconsistency

Staggering animations across too many elements

medium

Staggering 20+ list items 50ms apart creates a slow cascade the user has to wait through before they can interact with the page.

motionlistsperformance-perception

Tokens & Code

1

Anti-patterns related to how design tokens are consumed in code, build pipelines, and packaging.

Importing tokens from raw JSON instead of the published bindings

medium

Reading `tokens/global/colors.json` directly in product code bypasses the build pipeline's validation and reference resolution.

tokensbuilddistribution