Skip to main content

STEMBlock.ai - UI/UX Specification Document

Version: 1.0 Date: October 25, 2025 Target Audience: Kids (6-18 years) and Parents (varying tech proficiency)

Table of Contents​

  1. Design Philosophy
  2. Color System
  3. Typography
  4. Spacing and Layout
  5. Component Library
  6. Iconography
  7. Accessibility Guidelines
  8. Responsive Design
  9. User Role Interfaces

Design Philosophy​

Core Principles​

1. Age-Appropriate Design (6-18 years)

  • Ages 6-10: Larger buttons, playful illustrations, simple language, vibrant colors
  • Ages 11-14: Balanced design, gamification elements, achievement badges
  • Ages 15-18: More sophisticated interface, data visualization, professional feel

2. Parent-Friendly Navigation

  • Clear, jargon-free labels
  • Obvious navigation patterns
  • Dashboard summaries with plain language
  • Help tooltips throughout
  • Consistent layout across all sections

3. Educational & Encouraging

  • Positive reinforcement messaging
  • Progress visualization
  • Growth-focused feedback
  • Celebration of achievements

4. STEM-Focused Aesthetic

  • Robotics-inspired design elements
  • Technical but approachable
  • VEX branding integration
  • Engineering notebook aesthetics

Color System​

Primary Palette​

For Kids (Ages 6-14):

Primary Blue: #2E7CF6
- Main CTAs, links, active states
- RGB(46, 124, 246)
- Use: Buttons, navigation highlights

Secondary Purple: #8B5CF6
- Secondary actions, accents
- RGB(139, 92, 246)
- Use: Achievement badges, progress indicators

Success Green: #10B981
- Positive feedback, completed tasks
- RGB(16, 185, 129)
- Use: Success messages, checkmarks

Warning Orange: #F59E0B
- Alerts, pending items
- RGB(245, 158, 11)
- Use: Warnings, attention items

Error Red: #EF4444
- Errors, critical feedback
- RGB(239, 68, 68)
- Use: Error states, corrections needed

For Older Students (Ages 15-18) & Parents:

Deep Blue: #1E40AF
- Professional primary
- RGB(30, 64, 175)

Slate Gray: #475569
- Text, secondary elements
- RGB(71, 85, 105)

Teal Accent: #14B8A6
- Data visualization, charts
- RGB(20, 184, 166)

Neutral Palette​

White: #FFFFFF
Background: #F8FAFC (Slate 50)
Light Gray: #E2E8F0 (Slate 200)
Medium Gray: #64748B (Slate 500)
Dark Gray: #1E293B (Slate 800)
Black: #0F172A (Slate 900)

Semantic Colors​

Info: #3B82F6 (Blue 500)
Success: #10B981 (Green 500)
Warning: #F59E0B (Amber 500)
Error: #EF4444 (Red 500)

Gradient Accents (for visual interest)​

Hero Gradient:
  from: #2E7CF6 (Primary Blue)
  to: #8B5CF6 (Secondary Purple)

Achievement Gradient:
  from: #F59E0B (Warning Orange)
  to: #EF4444 (Error Red)

Typography​

Font Families​

Primary Font: Inter

  • Modern, readable, excellent for UI
  • Supports wide range of weights
  • Great screen readability

Display Font: Poppins

  • For headings and hero text
  • Playful but professional
  • Weights: 600 (SemiBold), 700 (Bold)

Monospace: JetBrains Mono

  • For code snippets
  • Programming feedback
  • Technical details

Type Scale​

For Kids (6-10):

Heading 1: 36px / 2.25rem (Poppins Bold)
Heading 2: 30px / 1.875rem (Poppins SemiBold)
Heading 3: 24px / 1.5rem (Poppins SemiBold)
Body Large: 18px / 1.125rem (Inter Regular)
Body: 16px / 1rem (Inter Regular)
Small: 14px / 0.875rem (Inter Regular)

For Teens & Adults (11-18 + Parents):

Heading 1: 32px / 2rem (Poppins Bold)
Heading 2: 24px / 1.5rem (Poppins SemiBold)
Heading 3: 20px / 1.25rem (Poppins SemiBold)
Body: 16px / 1rem (Inter Regular)
Small: 14px / 0.875rem (Inter Regular)
Caption: 12px / 0.75rem (Inter Regular)

Line Heights​

Tight: 1.25 (for headings)
Normal: 1.5 (for body text)
Relaxed: 1.75 (for long-form content)

Font Weights​

Regular: 400
Medium: 500
SemiBold: 600
Bold: 700

Spacing and Layout​

Spacing Scale (Tailwind-based)​

xs: 4px / 0.25rem
sm: 8px / 0.5rem
md: 16px / 1rem
lg: 24px / 1.5rem
xl: 32px / 2rem
2xl: 48px / 3rem
3xl: 64px / 4rem

Container Widths​

Mobile: 100% (no max-width)
Tablet: 768px
Desktop: 1024px
Wide: 1280px
Max Content Width: 1440px

Grid System​

  • 12-column grid for desktop
  • 6-column grid for tablet
  • 4-column grid for mobile
  • Gap: 24px (lg) for desktop, 16px (md) for mobile

Layout Patterns​

Dashboard Layout:

- Header: 64px height
- Sidebar: 256px width (collapsible on mobile)
- Main Content: Flexible
- Footer: 80px height

Card Spacing:

Padding: 24px (lg)
Gap between cards: 16px (md)
Border Radius: 12px

Component Library​

Buttons​

Primary Button

Background: Primary Blue (#2E7CF6)
Text: White
Padding: 12px 24px (py-3 px-6)
Border Radius: 8px
Font: Inter Medium 16px
Hover: Darken by 10%
Active: Scale 0.98
Shadow: 0 2px 8px rgba(46, 124, 246, 0.3)

Secondary Button

Background: Transparent
Border: 2px solid Primary Blue
Text: Primary Blue
Padding: 12px 24px
Border Radius: 8px
Hover: Background Primary Blue, Text White

Success Button (for completion)

Background: Success Green
Text: White
Same dimensions as Primary

Sizes:

  • Small: py-2 px-4 (8px 16px), text-sm
  • Medium: py-3 px-6 (12px 24px), text-base
  • Large: py-4 px-8 (16px 32px), text-lg

Cards​

Standard Card

Background: White
Border: 1px solid #E2E8F0
Border Radius: 12px
Padding: 24px
Shadow: 0 1px 3px rgba(0,0,0,0.1)
Hover: Shadow 0 4px 12px rgba(0,0,0,0.15)

Student Progress Card

Header: Gradient background (Hero Gradient)
Icon: White with subtle shadow
Title: White, Poppins SemiBold 20px
Content: White background, padding 20px

Achievement Badge Card

Border: 2px solid gradient
Background: White
Centered icon (48px)
Title below icon
Shadow: 0 4px 8px rgba(139, 92, 246, 0.2)

Forms​

Input Fields

Height: 44px (good for touch targets)
Padding: 12px 16px
Border: 1px solid #CBD5E1 (Slate 300)
Border Radius: 8px
Font: Inter Regular 16px
Focus: Border Primary Blue, Ring 3px rgba(46, 124, 246, 0.1)
Error: Border Error Red, Ring 3px rgba(239, 68, 68, 0.1)

Labels

Font: Inter Medium 14px
Color: Dark Gray (#1E293B)
Margin Bottom: 8px

Helper Text

Font: Inter Regular 12px
Color: Medium Gray (#64748B)
Margin Top: 4px

Error Text

Font: Inter Regular 12px
Color: Error Red
Icon: Alert circle

Top Navigation Bar

Height: 64px
Background: White
Border Bottom: 1px solid #E2E8F0
Shadow: 0 1px 3px rgba(0,0,0,0.05)
Logo: Left aligned, 40px height
Nav Items: Centered or right-aligned
User Menu: Far right

Sidebar Navigation

Width: 256px
Background: Slate 50 (#F8FAFC)
Item Height: 44px
Item Padding: 12px 16px
Active Item: Primary Blue background, White text
Hover: Slate 100 background
Icon Size: 20px

Breadcrumbs

Font: Inter Regular 14px
Color: Medium Gray
Separator: "/" or ">"
Current Page: Primary Blue, Medium weight

Alerts & Notifications​

Toast Notification

Width: 360px (mobile: 90%)
Padding: 16px
Border Radius: 8px
Shadow: 0 4px 12px rgba(0,0,0,0.15)
Position: Top right
Animation: Slide in from right

Types:
- Success: Green background, white text, checkmark icon
- Error: Red background, white text, X icon
- Warning: Orange background, dark text, exclamation icon
- Info: Blue background, white text, info icon

Banner Alert

Full width
Padding: 16px
Text: Centered
Close button: Right aligned
Background: Based on type (success, warning, error, info)

Progress Indicators​

Progress Bar

Height: 8px
Background: Light Gray (#E2E8F0)
Fill: Primary Blue or Success Green
Border Radius: 4px
Animate: Smooth transition on value change

Circular Progress (for scores)

Size: 120px
Stroke Width: 8px
Background Stroke: Light Gray
Foreground Stroke: Gradient (Hero Gradient)
Center Text: Score percentage, Bold 24px

Loading Spinner

Size: 40px (adjustable)
Color: Primary Blue
Animation: Smooth rotation

Badges & Tags​

Badge

Padding: 4px 12px
Border Radius: 12px (pill-shaped)
Font: Inter Medium 12px
Background: Light version of semantic color
Text: Dark version of semantic color

Example:
- New: Blue background (#DBEAFE), Blue text (#1E40AF)
- Completed: Green background (#D1FAE5), Green text (#065F46)

Tag

Padding: 6px 12px
Border Radius: 6px
Font: Inter Regular 14px
Background: Slate 100
Text: Slate 700
Removable: X icon on right

Data Visualization​

Chart Colors (for analytics)

Series 1: #2E7CF6 (Primary Blue)
Series 2: #8B5CF6 (Secondary Purple)
Series 3: #10B981 (Success Green)
Series 4: #F59E0B (Warning Orange)
Series 5: #14B8A6 (Teal Accent)

Table

Header Background: Slate 50
Header Text: Slate 700, Medium weight
Border: 1px solid Slate 200
Row Padding: 12px 16px
Row Hover: Slate 50 background
Zebra Striping: Optional, every other row Slate 50

Iconography​

Icon Library​

Recommended: Heroicons or Lucide Icons

  • Consistent style
  • Available in outline and solid versions
  • Good accessibility

Icon Sizes​

Extra Small: 16px (for inline text)
Small: 20px (for buttons, nav items)
Medium: 24px (for cards, headers)
Large: 32px (for empty states)
Extra Large: 48px+ (for illustrations)

Icon Usage​

Navigation Icons:

  • Home: House icon
  • Assessments: Clipboard/Test icon
  • Submissions: Upload/Folder icon
  • Reports: Chart/Graph icon
  • Forum: Chat/Message icon
  • Profile: User icon

Action Icons:

  • Add: Plus circle
  • Edit: Pencil
  • Delete: Trash
  • Download: Arrow down
  • Upload: Arrow up
  • Search: Magnifying glass
  • Filter: Funnel
  • Settings: Gear

Status Icons:

  • Success: Checkmark circle (green)
  • Error: X circle (red)
  • Warning: Exclamation triangle (orange)
  • Info: Info circle (blue)
  • Pending: Clock (orange)

VEX Robotics Icons:

  • Robot: Custom robot illustration
  • Code: Code brackets
  • Notebook: Book/Document
  • Team: Users group
  • Trophy: Award/Trophy

Accessibility Guidelines​

WCAG 2.1 AA Compliance​

Color Contrast Ratios:

  • Normal text: Minimum 4.5:1
  • Large text (18px+): Minimum 3:1
  • Interactive elements: Minimum 3:1 against background

Tested Combinations:

✓ Primary Blue (#2E7CF6) on White: 4.8:1
✓ Dark Gray (#1E293B) on White: 13.5:1
✓ White on Primary Blue: 4.8:1
✓ White on Success Green: 4.1:1

Keyboard Navigation​

  • All interactive elements must be keyboard accessible
  • Visible focus indicators (ring outline)
  • Tab order follows logical flow
  • Skip navigation links for screen readers

Focus Indicators​

Outline: 3px solid Primary Blue
Offset: 2px
Border Radius: Matches element

Screen Reader Support​

  • Semantic HTML (nav, main, article, aside, etc.)
  • ARIA labels for icon-only buttons
  • Alt text for all images
  • ARIA live regions for dynamic content
  • Form labels properly associated

Touch Targets​

  • Minimum size: 44x44px
  • Adequate spacing: 8px minimum between targets
  • Mobile-friendly tap areas

Responsive Design​

Breakpoints​

Mobile: 320px - 639px
Tablet: 640px - 1023px
Desktop: 1024px - 1279px
Wide: 1280px+

Mobile-First Approach​

Navigation:

  • Mobile: Hamburger menu
  • Tablet: Collapsible sidebar
  • Desktop: Persistent sidebar

Typography:

  • Mobile: Scale down by 10-15%
  • Tablet: Standard scale
  • Desktop: Standard scale

Layout:

  • Mobile: Single column, stacked cards
  • Tablet: 2-column grid
  • Desktop: 3-4 column grid, sidebars

Forms:

  • Mobile: Full width inputs, stacked
  • Tablet: 2-column for short inputs
  • Desktop: Horizontal layout for related fields

User Role Interfaces​

Student Interface (Ages 6-18)​

Visual Style:

  • Bright, encouraging colors
  • Large, clear buttons
  • Progress visualization (stars, levels, badges)
  • Gamification elements
  • Friendly illustrations

Key Features:

  • Dashboard with current assignments
  • Progress tracker (visual, encouraging)
  • Achievement showcase
  • Simple navigation
  • Help tooltips

Age Adaptations:

  • 6-10: Larger text, more illustrations, simplified language
  • 11-14: Balanced design, achievement focus
  • 15-18: More data, professional feel, detailed analytics

Parent Interface​

Visual Style:

  • Clean, professional
  • Clear hierarchy
  • Simplified language
  • Summary-focused
  • Minimal technical jargon

Key Features:

  • Child selector (if multiple children)
  • Executive summary dashboard
  • Plain language reports
  • Progress timeline
  • Simple navigation with labels
  • Help center easily accessible

Parent-Friendly Elements:

  • "What does this mean?" tooltips
  • Glossary of terms
  • Video tutorials
  • Clear next steps
  • Email digest options

Coach Interface​

Visual Style:

  • Data-rich
  • Analytics-focused
  • Professional
  • Efficient workflow
  • Multi-student management

Key Features:

  • Class overview dashboard
  • Student performance matrix
  • At-risk student alerts
  • Bulk actions
  • Detailed analytics
  • Export capabilities

Admin Interface​

Visual Style:

  • Technical
  • Comprehensive
  • System-focused
  • Data tables
  • Management tools

Key Features:

  • User management
  • System analytics
  • Configuration settings
  • Audit logs
  • Reporting tools

Animation & Transitions​

Principles​

  • Purposeful: Animations guide attention
  • Quick: 150-300ms for most transitions
  • Smooth: Ease-in-out timing function
  • Consistent: Same animations for similar actions

Common Animations​

Button Hover:

Transition: all 0.2s ease-in-out
Transform: scale(1.02)
Shadow: Increase elevation

Card Hover:

Transition: all 0.3s ease-in-out
Shadow: Increase from 1 to 2
Transform: translateY(-2px)

Modal/Dialog:

Enter: Fade in + scale from 0.95 to 1 (200ms)
Exit: Fade out + scale from 1 to 0.95 (150ms)
Backdrop: Fade in/out (200ms)

Notifications:

Enter: Slide in from right (300ms)
Exit: Slide out to right (200ms)

Page Transitions:

Duration: 200ms
Effect: Fade in new content

Dark Mode (Future Consideration)​

Color Adjustments​

Background: #0F172A (Slate 900)
Surface: #1E293B (Slate 800)
Text: #F8FAFC (Slate 50)
Primary: Lighter shade of Primary Blue (#60A5FA)

Note: Dark mode is not in MVP scope but architecture should support it.

Brand Guidelines​

Logo Usage​

  • Minimum Size: 120px width
  • Clear Space: 16px around logo
  • Backgrounds: White or Slate 50 preferred
  • Color Versions: Full color, white, black

Voice & Tone​

For Students:

  • Encouraging and positive
  • "You're doing great!"
  • "Let's improve this together"
  • Avoid: "Wrong", "Failed", "Poor"

For Parents:

  • Clear and informative
  • "Your child is making progress in..."
  • Professional but friendly
  • Avoid: Technical jargon without explanation

For Coaches:

  • Professional and efficient
  • Data-driven language
  • Actionable insights

Implementation Notes​

Technology Integration​

Tailwind CSS Configuration:

// Extend default theme with custom colors
colors: {
  'stem-blue': '#2E7CF6',
  'stem-purple': '#8B5CF6',
  'stem-green': '#10B981',
  // etc.
}

shadcn/ui Components:

  • Use as base
  • Customize with STEMBlock color palette
  • Maintain consistent component API

Component Library Structure​

/components
  /ui (shadcn base components)
  /student (student-specific components)
  /parent (parent-specific components)
  /coach (coach-specific components)
  /shared (cross-role components)

Quality Checklist​

Before marking design complete, ensure:

  • All colors meet WCAG AA contrast requirements
  • Typography is legible at all sizes
  • Touch targets are minimum 44x44px
  • Keyboard navigation works throughout
  • Screen reader tested
  • Responsive on mobile, tablet, desktop
  • Consistent spacing throughout
  • All interactive elements have clear states (default, hover, active, focus, disabled)
  • Loading states defined for all async actions
  • Error states designed for all forms
  • Empty states designed for all lists/tables
  • Age-appropriate for full range (6-18 years)
  • Parent-friendly language and navigation

Document Status: Draft for UX Designer Next Steps: Create wireframes based on this specification Feedback: Share with educational advisors and pilot users