Design System — Design Document

1. Overview & principles

1.1 Purpose

• This system is for AOPA's digital design & branding.
• It serves devs, design and content producers.

1.2 Design principles

• Clear Communication
• Simplified Structures
• Impactful Patterns
• REfined Typography

1.3 Brand positioning

• Mission, voice, and personality in 1–2 paragraphs.
• How the design system supports the brand (tone of UI, imagery, motion).

2. Foundations

2.1 Color

• Palette: Primary, secondary, neutrals (with hex/Pantone/HSL if needed).
• Semantic roles: Text (primary, secondary, muted), backgrounds (page, surface, overlay), borders, focus, error, success, warning.
• Usage rules: When to use which role; contrast and accessibility (e.g. WCAG AA).
• Dark mode (if applicable): Mapping from light roles to dark; any inversions or exceptions.

2.2 Typography

• Type scale: Display, heading levels, body, caption, overline—sizes and line heights.
• Font families: Primary and secondary; usage (headings vs body vs UI).
• Weights: Which weights exist and when to use them.
• Prose/editorial: Rules for long-form content (line length, spacing, lists, blockquotes).

2.3 Spacing & layout

• Spacing scale: Named scale (e.g. xs, sm, md, lg, xl) with values; usage (padding, margins, gaps).
• Grid: Column count, gutter, margin; breakpoints and when the grid changes.
• Breakpoints: Named breakpoints (e.g. sm, md, lg, xl) and what they represent (device / viewport intent).

2.4 Motion & animation

• Duration scale: Short, medium, long (e.g. 150ms, 300ms, 500ms) and when to use each.
• Easing: Standard curves (ease-in, ease-out, ease-in-out, custom) and use cases.
• Principles: When we animate (feedback, focus, transition) and when we don’t.

2.5 Iconography

• Style: Outline vs solid; stroke weight; size scale.
• Library/source: Which set we use; how to add or request icons.
• Usage: Sizing with text, alignment, color (inherit vs semantic).

2.6 Imagery & media

• Photography: Style, cropping, treatment (e.g. no heavy filters).
• Illustration: Style (if any); when to use illustration vs photo vs icon.
• Aspect ratios: Standard ratios for cards, heroes, thumbnails.
• Accessibility: Alt text expectations; decorative vs meaningful.

3. Components

For each component, keep the doc design-focused; implementation can live in code/Storybook.

3.1 Component template (repeat per component)

Component name

• Purpose: What it’s for and when to use it.
• Variants: Primary, secondary, sizes, states (default, hover, focus, disabled, error).
• Anatomy: Labeled diagram or list (e.g. icon, label, helper text, trailing icon).
• Specs: Size, padding, border radius, typography, color roles.
• Composition: What it can contain (e.g. text only, icon + text, slots).
• Do’s and don’ts: 2–3 each; reference principles where it helps.
• Related: Links to patterns or other components.

Suggested order: Start with primitives (Button, Text, Icon, Input, Checkbox, etc.), then patterns (Card, Form field, Modal, Nav item).

4. Patterns

Higher-level, cross-component guidance.

4.1 Layout patterns

• Page structure (header, main, sidebar, footer).
• Containers (narrow, medium, full).
• Stacking and grouping (sections, cards, lists).

4.2 Navigation

• Global nav, local/tabs, breadcrumbs, pagination.
• When to use which; hierarchy and placement.

4.3 Forms & inputs

• Label placement, helper/error text, required indicator.
• Validation and error state; multi-step flows if relevant.

4.4 Feedback & status

• Toasts, banners, inline messages.
• Loading states (skeletons, spinners) and when to use each.

4.5 Content patterns

• Article/page layout; headings, lists, blockquotes, code.
• Cards for previews, feature lists, CTAs.

5. Accessibility

• Target: WCAG 2.1 AA (or other standard); any AAA goals.
• Color: Contrast ratios; never rely on color alone.
• Focus: Visible focus states; tab order and keyboard use.
• Motion: Respect prefers-reduced-motion; document any exceptions.
• Content: Headings hierarchy, alt text, form labels.

6. Responsive & platform

• Breakpoint behavior: How layout and components change at each breakpoint.
• Touch targets: Minimum size (e.g. 44px); spacing for touch.
• Platform notes: Any differences for native, email, or embedded contexts.

7. Governance & maintenance

• Ownership: Who approves changes to foundations and components.
• Contribution: How to propose new components or tokens (e.g. request template, review process).
• Versioning: How we communicate breaking vs additive changes (link to changelog or “What’s new”).
• Design tools: Where the canonical Figma library lives; how often it’s synced with this doc.

8. Appendix

• Changelog: Summary of major doc and system updates.
• Glossary: Terms used in the doc (e.g. “token,” “variant,” “primitive”).
• References: Links to brand guidelines, research, or external standards.