Skip to main content

STEMBlock.ai Mockups - Setup Instructions

Quick Start Guide​

Follow these steps to view the interactive HTML/React mockups in your browser.

Step 1: Check Prerequisites​

Ensure you have Node.js installed:

node --version

Required: Node.js 18.x or higher

If you don't have Node.js installed:

  • Mac: brew install node
  • Windows: Download from nodejs.org
  • Linux: sudo apt install nodejs npm

Step 2: Navigate to Mockups Directory​

cd .temp/mockups

Step 3: Install Dependencies​

npm install

This will install:

  • Next.js 14
  • React 18
  • Tailwind CSS
  • TypeScript
  • Other required dependencies

Note: First installation may take 2-3 minutes.

Step 4: Start Development Server​

npm run dev

You should see output like:

- Local:        http://localhost:3000
- Ready in 2.5s

Step 5: Open in Browser​

Navigate to: http://localhost:3000

You'll see the home page with links to all mockups organized by user role.

What You'll See​

Home Page (/)​

Central navigation hub with links to:

  • 📘 Student Views (young & teen dashboards, assessments, etc.)
  • 👨‍👩‍👧 Parent Views (dashboard, reports)
  • 👨‍🏫 Coach Views (class management, reviews)
  • 🎨 Component Library (all UI components)

Student Mockups​

Dashboard for Young Students (6-10 years)

  • Bright, colorful design
  • Large buttons and text
  • Gamification elements (stars, badges)
  • Encouraging language
  • URL: /student/dashboard-young

Dashboard for Teens (15-18 years)

  • Professional interface
  • Data analytics
  • Clean, modern design
  • Technical language
  • URL: /student/dashboard-teen

Parent Mockups​

Parent Dashboard

  • Multi-child selector
  • Plain-language summaries
  • "What This Means" explanations
  • Simple visualizations
  • URL: /parent/dashboard

Coach Mockups​

Coach Dashboard

  • Class performance matrix
  • At-risk student alerts
  • Pending submissions
  • Quick actions
  • URL: /coach/dashboard

Component Library​

UI Components Showcase

  • All buttons, cards, forms
  • Color palette
  • Typography examples
  • Interactive examples
  • URL: /components

Viewing on Mobile​

Method 1: Same Device​

  1. Start the dev server: npm run dev
  2. Resize your browser to mobile width
  3. Inspect with browser DevTools (Cmd+Option+I / F12)
  4. Toggle device toolbar

Method 2: Different Device​

  1. Find your local IP:

    # Mac/Linux
    ifconfig | grep "inet "

    # Windows
    ipconfig

  2. Start dev server: npm run dev

  3. On mobile, navigate to:

    http://YOUR_IP:3000
    # Example: http://192.168.1.10:3000

Keyboard Shortcuts​

While viewing mockups:

  • Cmd+R / F5: Refresh page
  • Cmd+Shift+I / F12: Open DevTools
  • Cmd+Option+J / Ctrl+Shift+J: Open Console
  • Tab: Navigate between interactive elements

Stopping the Server​

Press Ctrl+C in the terminal where the server is running.

Troubleshooting​

Problem: Port 3000 Already in Use​

Solution: Use a different port:

npx next dev -p 3001

Then navigate to http://localhost:3001

Problem: "Cannot find module"​

Solution: Reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

Problem: Styles Not Appearing​

Solution:

  1. Stop the server (Ctrl+C)
  2. Delete .next folder: rm -rf .next
  3. Restart: npm run dev

Problem: TypeScript Errors​

Solution: Ensure Node.js version is 18.x or higher:

node --version

Update if necessary.

Tips for Best Experience​

1. Use Chrome or Firefox​

Best developer tools and CSS support.

2. Test Responsive Design​

  • Use browser DevTools device toolbar
  • Test on actual mobile devices
  • Check tablet sizes (768px width)

3. Take Screenshots​

For documentation or presentations:

  • Use browser's built-in screenshot tool
  • Or DevTools: Cmd+Shift+P → "Capture screenshot"

4. Check Accessibility​

  • Enable screen reader
  • Navigate with keyboard only (Tab key)
  • Test color contrast

5. Compare Against Specs​

Reference documents in .temp/:

  • ui-ux-specification.md
  • design-system.md
  • wireframe-descriptions.md

Making Changes​

Edit Components​

  1. Open /components/ui.tsx
  2. Modify component code
  3. Save file
  4. Changes appear automatically (hot reload)

Change Colors​

  1. Open tailwind.config.js
  2. Edit color values in theme.extend.colors
  3. Save file
  4. Refresh browser

Add New Pages​

  1. Create folder in app/, e.g., app/new-page/
  2. Add page.tsx file
  3. Import components: import \{ Card \} from '@/components/ui'
  4. Add link from home page

Sharing Mockups​

Method 1: Screenshots​

Take screenshots of each page and share as images.

Method 2: Screen Recording​

Record a walkthrough video showing navigation.

Method 3: Deploy Online​

Deploy to Vercel (free):

npm install -g vercel
vercel

Follow prompts to deploy and get a public URL.

Method 4: Share Locally​

Run on one computer and share local network URL with team.

Additional Resources​

Documentation​

  • Main README: /mockups/README.md
  • Design Specs: /.temp/ui-ux-specification.md
  • Component Docs: /.temp/design-system.md
  • Wireframes: /.temp/wireframe-descriptions.md

Technology Docs​

Next Steps​

For Designers​

  1. ✅ View all mockups in browser
  2. ✅ Take screenshots for Figma reference
  3. ✅ Test responsive behavior
  4. ✅ Validate color choices
  5. ✅ Share with stakeholders

For Developers​

  1. ✅ Review component structure
  2. ✅ Extract Tailwind patterns
  3. ✅ Study TypeScript interfaces
  4. ✅ Test accessibility
  5. ✅ Plan implementation

For Product Team​

  1. ✅ Conduct user testing
  2. ✅ Gather feedback
  3. ✅ Validate navigation
  4. ✅ Test language clarity
  5. ✅ Approve for development

Questions?​

  1. Check README.md in /mockups/ directory
  2. Review design documentation in .temp/
  3. Inspect component code in /components/ui.tsx
  4. Test in browser DevTools

Happy exploring! 🚀

These mockups represent the complete STEMBlock.ai design system, ready for implementation.