General writing principles
Use American english as the language of the documentation.
- German examples are preferred as the content of OTTO ist german.
Write in a clear, direct and objective tone.
Use short sentences and active phrasing.
Content should be aimed at designers.
Avoid jargon and internal abbreviations.
Use sentence case (e.g. "Content guidelines") for page titles and heading
Documentation page structure
Every page follows the same structure to keep it easy to navigate. Not every page contains all of the outline points described, but always the points that are relevant and necessary for understanding the foundation or the component’s purpose, behavior, and usage.
The pages are divided into two tabs: usage for components or overview for foundations (contains the following outlines) and implementation (contains links to the technical documentation).
Component page
1. Anatomy
Anatomy explains the essential parts of the component. Use a labeled visual with consistent terminology.
2. Variants
Variants describe all available types, sizes, or stylistic alternatives of the component. Each variant must include when and why it should be used. Support the description with labeled visuals.
3. Behaviour
This section describes how the component acts and responds to user interaction. It is subdivided in the following sections:
3.1. States: A visual listing of all states such as default, hover, focus, active, disabled, or error.
3.2. Interaction: Describes whether the component is interactive, how users interact with it, and what kind of feedback they receive.
3.3. Animation: Explains any motion or transitions that occur during interaction.
3.4. Fitting: Shows how the component adapts to different layouts or container sizes (responsive behaviour).
3.5. Placement: Explains where and how the component should be positioned within an interface - addressing spacing, alignment, and contextual rules.
4. Component vs. component
This section describes the differences between two related or similar components that may require clarification.
5. Best practices
Contains rules for use, what constitutes good application and what mistakes should be avoided, using visuals for dos and don'ts.
6. Content guidelines
Describes how text should be used within the component, including tone, microcopy, and formatting. Provides examples of effective and ineffective copy to ensure usability.
7. Accessibility
Details how the component supports accessibility requirements for keyboard, screen readers, contrast, and interaction. Provides a link to the technical accessibility documentation in storybook.
8. Status
Shows the date on which the page was last changed.
9. Related components
Links to related components.
Foundation page
1. Overview
Covers everything specific to anatomy, definitions, variants, characteristics, applying etc. Every aspect adapted to the respective foundation.
2. Best practices
Contains rules for use, what constitutes good application and what mistakes should be avoided, using visuals for dos and don'ts.
3. Accessibility
Describes what WCAG requirements must be met.
4. Fragments
Links to the fragments/ token used in storybook.
5. Status
Shows the date on which the page was last changed.
6. Related foundations
Links to related foundations.
How to start checklist
How to start the documentation with a thorough benchmarking:
Write down your own thoughts and knowledge.
Check status quo: Briefing file in Figma
Check status quo: Documentation file in Figma
Check status quo: Technical documentation in the component library
Check the previous design system Global pattern
Benchmark other design system (e.g.): Google Material Design 3, Microsoft Fluent 2, eBay Playbook, Uber Base, Atlassian
Write down the text with help of Copilot Guideline Agent, e.g. in Miro
Visualize the graphics in Figma
Transfer everything to the documentation platform
Place the link to the documentation page in the description of the component in Figma