Do and Dont Examples

Do and dont examples present correct and incorrect usage patterns side by side, helping design system users understand not just how to use components but how to avoid misusing them. This documentation pattern proactively addresses common mistakes and design violations. Visual comparison makes proper usage immediately clear.

What Are Do and Dont Examples

Do and dont examples are paired demonstrations showing recommended approaches alongside discouraged approaches. The “do” example shows correct implementation or design usage, while the “dont” example shows a common mistake or misuse. Explanatory text accompanies each example to clarify why one approach is preferred.

This pattern appears throughout design system documentation for both code implementation and design usage. Implementation examples might show correct prop usage versus incorrect patterns. Design examples might show appropriate context for a component versus situations where alternatives are better suited.

How Do and Dont Examples Work

Effective do and dont examples require clear visual differentiation between correct and incorrect patterns. Common approaches use color coding with green checkmarks for do examples and red X marks for dont examples. Layout typically places examples side by side or in clearly separated sections with consistent visual treatment.

Each example pair addresses one specific concept or decision point. Combining multiple lessons in a single pair dilutes the message and confuses readers. The accompanying explanation describes why the incorrect approach is problematic, not just that it is wrong.

Documentation components for do and dont patterns standardize presentation across the design system. Authors use these components to ensure consistent formatting rather than recreating the pattern for each instance. The component handles visual treatment while authors provide content.

Key Considerations

• Visual differentiation through icons, colors, and labels prevents confusion about which example to follow
• Each pair should address exactly one concept to maintain clarity
• Explanations should describe the reasoning behind the recommendation, not just state rules
• The incorrect example should represent realistic mistakes developers actually make

Common Questions

What topics benefit most from do and dont examples?

Topics that commonly lead to misuse benefit most from do and dont examples. Component usage guidelines showing when to use one component versus another suit this format well. Accessibility requirements like proper labeling often need do and dont demonstrations. Design guidelines about spacing, color usage, and typography benefit from visual comparison. Code patterns where multiple approaches exist but one is preferred, such as composition versus prop drilling, work well. Teams should create do and dont examples in response to observed misuse patterns and support questions.

How do teams prevent users from copying dont examples?

Preventing accidental copying of incorrect examples requires deliberate design. Never include copy buttons on dont examples while including them on do examples. Use non-functional or clearly fake code in dont examples where possible. Place visual warnings directly adjacent to incorrect code. Some documentation systems render dont examples in a way that prevents text selection. Consider showing dont examples as images rather than text when copy prevention is critical. Despite these measures, accompanying explanations remain essential for users who may see examples out of context.

Summary

Do and dont examples guide correct usage by contrasting recommended and discouraged approaches. Clear visual differentiation, focused scope, and explanatory text make these examples effective. This documentation pattern proactively addresses common mistakes, reducing support requests and improving implementation consistency.