Skip to content

DESIGN.md

Latest commit

 

History

History
370 lines (299 loc) · 12.3 KB

DESIGN.md

File metadata and controls

370 lines (299 loc) · 12.3 KB

DESIGN.md — [Your Product Name]

[One-line description of the visual identity and personality]

1. Design Overview

Product type: [SaaS dashboard / E-commerce / Marketing site / Mobile app / etc.] Target audience: [Who uses this product] Design philosophy: [2-3 sentences describing the core visual approach] Personality keywords: [3-5 adjectives, e.g., "trustworthy, precise, warm"] Reference products: [2-3 existing products whose aesthetic is closest]

Brand Voice in UI

  • Headlines: [Tone — e.g., "Confident and direct. No question marks in hero copy."]
  • Body text: [Tone — e.g., "Conversational but informed. Second person."]
  • Microcopy: [Tone — e.g., "Friendly, never cute. 'Save changes' not 'You're all set! 🎉'"]

2. Color Palette

Primary

Token Hex Usage
--color-primary #______ Primary actions, CTAs, active states
--color-primary-hover #______ Hover state for primary elements
--color-primary-light #______ Backgrounds, badges, subtle highlights
--color-primary-dark #______ Text on light primary backgrounds

Neutrals

Token Hex Usage
--color-bg #______ Page background
--color-surface #______ Card/panel backgrounds
--color-border #______ Borders, dividers
--color-text-primary #______ Headings, important text
--color-text-secondary #______ Body text, descriptions
--color-text-muted #______ Placeholders, disabled text

Semantic

Token Hex Usage
--color-success #______ Confirmations, positive states
--color-warning #______ Caution states, pending
--color-error #______ Errors, destructive actions
--color-info #______ Informational banners, tips

Dark Mode (if applicable)

Token Light Dark
--color-bg #______ #______
--color-surface #______ #______
--color-text-primary #______ #______

Color Rules

  • [Rule 1 — e.g., "Primary color is reserved for interactive elements only"]
  • [Rule 2 — e.g., "Never use semantic colors for decorative purposes"]
  • [Rule 3 — e.g., "Dark mode inverts surfaces, not brand colors"]

3. Typography

Font Stack

  • Display/Headings: [Font name], fallback: [fallback]
  • Body: [Font name], fallback: [fallback]
  • Monospace: [Font name], fallback: [fallback]

Type Scale

Level Size Weight Line Height Letter Spacing Usage
Display __px ___ . __px Hero headlines
H1 __px ___ . __px Page titles
H2 __px ___ . __px Section headings
H3 __px ___ . __px Card titles, subsections
H4 __px ___ . __px Labels, small headings
Body __px ___ . __px Paragraphs, descriptions
Small __px ___ . __px Captions, metadata
Tiny __px ___ . __px Badges, fine print

Typography Rules

  • [Rule 1 — e.g., "Never go below 14px for body text"]
  • [Rule 2 — e.g., "Headings use tight line-height (1.1-1.2), body uses loose (1.5-1.6)"]
  • [Rule 3 — e.g., "Maximum 60-70 characters per line for body text"]
  • [Rule 4 — e.g., "Bold (600+) only for headings and emphasis — never for entire paragraphs"]

4. Component Styles

Buttons

Primary

Background: var(--color-primary)
Text: #FFFFFF
Padding: __px __px
Border-radius: __px
Font: __px/__00
Hover: [describe hover state]
Active: [describe active state]
Disabled: opacity 0.5, cursor not-allowed

Secondary

Background: transparent
Border: 1px solid var(--color-border)
Text: var(--color-text-primary)
[... same structure]

Destructive

Background: var(--color-error)
Text: #FFFFFF
[... same structure]

Button Rules

  • [e.g., "One primary button per view. Multiple secondaries are fine."]
  • [e.g., "Destructive actions require a confirmation step."]
  • [e.g., "Minimum touch target: 44x44px on mobile."]

Inputs

Background: var(--color-bg) or var(--color-surface)
Border: 1px solid var(--color-border)
Border-radius: __px
Padding: __px __px
Font: __px body font
Focus: 2px ring var(--color-primary), border color change
Error: border var(--color-error), error message below in --color-error at __px
Placeholder: var(--color-text-muted)

Cards

Background: var(--color-surface)
Border: [1px solid var(--color-border) OR none]
Border-radius: __px
Padding: __px
Shadow: [shadow value or "none"]
Hover: [describe if interactive]

Tables

Header: [background, text style, border]
Row: [alternating colors or borders]
Row hover: [highlight color]
Cell padding: __px __px
Alignment: [left for text, right for numbers]

Modals / Dialogs

Overlay: rgba(0,0,0,0.__)
Panel: var(--color-surface), __px radius, __px padding
Max-width: __px
Shadow: [shadow value]
Close button: [position and style]

Navigation

[Describe nav pattern: sidebar, topbar, tabs, etc.]
Active state: [how to indicate current page]
Hover state: [subtle highlight]
Mobile: [hamburger, bottom nav, drawer, etc.]

5. Layout & Spacing

Grid System

  • Max content width: ____px
  • Columns: [12-column / flexible]
  • Gutter: __px
  • Page margin: __px (desktop), __px (mobile)

Spacing Scale

Token Value Usage
--space-xs __px Tight gaps, icon-to-text
--space-sm __px Related element gaps
--space-md __px Standard component padding
--space-lg __px Section gaps
--space-xl __px Major section separators
--space-2xl __px Page-level vertical rhythm

Responsive Breakpoints

Name Width Behavior
Mobile < ___px [Single column, stacked, bottom nav]
Tablet ___px – ___px [Describe layout shift]
Desktop > ___px [Full layout, sidebar visible, etc.]

Layout Rules

  • [e.g., "Spacing uses a 4px base grid — all values are multiples of 4"]
  • [e.g., "Cards in a grid: 3 columns desktop, 2 tablet, 1 mobile"]
  • [e.g., "Sidebar width: 240px fixed, collapsible to 64px icon-only"]

6. Elevation & Depth

Shadow Scale

Level Value Usage
None none Flat elements, inline content
Low 0 1px 2px rgba(0,0,0,0.__) Cards, buttons at rest
Medium 0 4px 8px rgba(0,0,0,0.__) Dropdowns, popovers
High 0 8px 24px rgba(0,0,0,0.__) Modals, floating panels

Depth Philosophy

  • [e.g., "Shadows are subtle — never heavier than 0.12 opacity"]
  • [e.g., "Use borders instead of shadows for in-page hierarchy"]
  • [e.g., "Elevation increases with interaction importance, not visual importance"]

7. Iconography & Imagery

Icons

  • Style: [Outlined / Filled / Duo-tone]
  • Size: __px default, __px small, __px large
  • Stroke width: __px
  • Library: [Lucide / Heroicons / Phosphor / custom]
  • Color: Inherit from text color — never standalone color unless semantic

Imagery

  • Style: [Photography / Illustration / Abstract / None]
  • Treatment: [e.g., "Photos use 8px radius, never full-bleed in cards"]
  • Aspect ratios: [e.g., "16:9 for hero, 1:1 for avatars, 4:3 for thumbnails"]

Illustration Rules

  • [e.g., "Illustrations use the primary palette — max 3 colors per illustration"]
  • [e.g., "No realistic shadows in illustrations — flat or isometric only"]

8. Animation & Motion

Timing

Type Duration Easing Usage
Micro 100-150ms ease-out Button press, toggle
Standard 200-300ms ease-in-out Dropdown, accordion
Emphasis 300-500ms cubic-bezier(0.16, 1, 0.3, 1) Page transitions, modals

Motion Rules

  • [e.g., "Entrances: fade + translateY(8px). Exits: fade only."]
  • [e.g., "Never animate layout properties (width, height) — use transform and opacity"]
  • [e.g., "Respect prefers-reduced-motion: disable all non-essential animation"]
  • [e.g., "Loading spinners: 800ms rotation, infinite, linear"]

9. Design Guardrails

Do

  • [e.g., "Use consistent border-radius across all components"]
  • [e.g., "Maintain 4:1 minimum contrast for text"]
  • [e.g., "Use the spacing scale — no magic numbers"]
  • [e.g., "Always include focus-visible styles on interactive elements"]

Don't

  • [e.g., "Don't use more than 2 font families"]
  • [e.g., "Don't center-align body text longer than 2 lines"]
  • [e.g., "Don't use color as the only indicator of state"]
  • [e.g., "Don't mix shadow elevation levels within the same container"]
  • [e.g., "Don't use opacity to create disabled-looking non-disabled elements"]

10. Accessibility Standards

Compliance Level

WCAG 2.1 AA minimum.

Color Contrast

Element Minimum Ratio Applies To
Normal text 4.5:1 Body text, labels, descriptions
Large text (18px+ bold or 24px+) 3:1 Headings, display text
UI components 3:1 Borders, icons, focus rings
Decorative None Backgrounds, dividers

Keyboard Navigation

  • All interactive elements focusable via Tab
  • Focus order follows visual order (left-to-right, top-to-bottom)
  • Focus-visible style: [describe — e.g., "2px solid var(--color-primary), 2px offset"]
  • Escape closes modals, popovers, and dropdowns
  • Enter/Space activates buttons and links

Screen Reader

  • All images have alt text (decorative images use alt="")
  • Form inputs have associated labels
  • Error messages linked to inputs via aria-describedby
  • Dynamic content changes announced via aria-live
  • Page regions use semantic HTML (<header>, <main>, <nav>, <footer>)

Touch Targets

  • Minimum: 44x44px
  • Recommended: 48x48px
  • Spacing between targets: minimum 8px

11. Edge Cases & Error Patterns

Empty States

[Describe empty state pattern]
- Illustration or icon: [yes/no, style]
- Headline: [e.g., "16px/600, neutral text"]
- Description: [e.g., "14px/400, muted text, max 2 lines"]
- CTA: [e.g., "Primary button if action available"]

Loading States

  • Skeleton screens: [describe — e.g., "Use animated pulse on #F3F4F6 blocks matching content shape"]
  • Spinners: [describe — e.g., "20px spinner, --color-primary, for inline loading"]
  • Progress bars: [describe — e.g., "4px height, --color-primary fill, --color-border track"]

Error States

  • Form errors: [inline below field, icon + red text, field border turns red]
  • Page errors: [centered illustration + message + retry button]
  • Toast/snackbar: [position, style, auto-dismiss timing]
  • Destructive confirmations: [modal with red button, explicit action label]

Overflow & Long Content

  • Truncation: [single line: ellipsis, multi-line: -webkit-line-clamp with count]
  • Tables: [horizontal scroll on mobile, or responsive card layout]
  • Long names/titles: [wrap or truncate — specify which components]

12. Agent Instructions

These are explicit rules for AI coding agents generating UI with this design system.

Before Generating

  1. Read this entire DESIGN.md before writing any CSS or component code.
  2. Use the exact token values defined above — never approximate or "close enough."
  3. When in doubt between two options, choose the more restrained one.

During Generation

  • Use CSS custom properties for all color, spacing, and typography values.
  • Generate semantic HTML (<button> not <div onClick>).
  • Include hover, focus, active, and disabled states for all interactive elements.
  • Apply the responsive breakpoints — every layout must work at all three sizes.
  • Include prefers-reduced-motion media query for animations.
  • Use the spacing scale — no arbitrary pixel values.

After Generating

  • Verify color contrast meets the ratios in Section 10.
  • Ensure keyboard navigation works (Tab, Enter, Escape).
  • Check empty/loading/error states are handled, not just the happy path.

Common AI Agent Mistakes to Avoid

  • Generating shadows heavier than specified in the elevation system
  • Using the primary color for decorative elements (it's reserved for actions)
  • Forgetting focus-visible styles on custom interactive elements
  • Using px for font sizes in components that should scale (use rem)
  • Creating buttons without minimum touch targets (44px)
  • Centering everything — respect the alignment rules in Section 5