reference / implementation-notes

Implementation Notes for AI Coding Starter Kit

This document contains important guidelines, patterns, and methodologies that should be followed consistently across the project. It serves as a reference for all developers working on the AI Coding Starter Kit.

Project Philosophy

The AI Coding Starter Kit is an open-source project designed to help beginners create real projects with AI assistance. Our design and communication should reflect:

  • Approachability: Content should be welcoming and accessible to beginners
  • Community-focus: Emphasize the open-source, collaborative nature of the project
  • Educational value: Highlight learning opportunities and skill development
  • Practical application: Focus on building real, usable projects

Design Language

Visual Style

  • Color palette: Gradients from violet to cyan for emphasis, with subtle background gradients
  • Typography: Clear hierarchy with larger, bolder headings and readable body text
  • Imagery: Use illustrations and screenshots that demonstrate the building process
  • Components: Use cards with subtle shadows and rounded corners for content grouping
  • Badges: Use badges to highlight important information (e.g., "Open Source", "Popular")

Tone and Voice

  • Conversational: Use friendly, approachable language
  • Direct: Be clear and concise in instructions and explanations
  • Encouraging: Emphasize that users can build real projects regardless of coding experience
  • Community-oriented: Reference the community and collaborative aspects of the project

Layout Structure

Standard Page Layout

All pages should follow this consistent layout structure:

<div className="flex flex-col min-h-screen">
 <div className="container py-10 max-w-6xl mx-auto px-4 sm:px-6 lg:px-8">
   {/* Page content */}
 </div>
</div>

This structure ensures:

  • Content is properly centered in the viewport
  • Pages have consistent padding and margins
  • The layout is responsive across different screen sizes

Container Constraints

Use these container constraints consistently:

  • max-w-6xl to limit the maximum width
  • mx-auto to center the container
  • Responsive padding with px-4 sm:px-6 lg:px-8

Two-Column Layout

For pages with a sidebar (like project details and tool pages), use this grid structure:

<div className="grid gap-6 md:grid-cols-[2fr_1fr]">
 {/* Main content column */}
 <div className="space-y-6">
   {/* Content components */}
 </div>
 
 {/* Sidebar column */}
 <div className="space-y-6">
   {/* Sidebar components */}
 </div>
</div>

This ensures:

  • Proper spacing between columns
  • Responsive behavior (stacks vertically on mobile)
  • Consistent proportions (2:1 ratio between main content and sidebar)

Component Patterns

Card Components

When using Card components:

  • Use consistent padding with <CardHeader> and <CardContent> components
  • Maintain spacing between cards with space-y-6 on the parent container
  • For clickable cards, use hover:bg-muted/50 transition-colors for hover effects
  • Consider using backdrop-blur-sm with semi-transparent backgrounds for a modern look

Navigation Components

For phase navigation:

  • Use the <PhaseNavigation> component for consistent styling
  • Ensure it spans the full width of its container
  • Add appropriate spacing with mb-6 or similar

Badge Components

Use badges to highlight important information:

  • For open source indicators: <Badge variant="outline" className="px-3 py-1 border-violet-200 bg-violet-100/50 text-violet-800">
  • For difficulty levels: <Badge className="bg-cyan-600">Beginner</Badge>
  • For popularity: <Badge className="bg-violet-600">Popular</Badge>

Visual Elements

Gradients

Use gradients consistently:

  • For text highlights: bg-gradient-to-r from-cyan-500 to-violet-500 text-transparent bg-clip-text
  • For button backgrounds: bg-gradient-to-r from-violet-600 to-violet-500 hover:from-violet-700 hover:to-violet-600
  • For section backgrounds: bg-gradient-to-br from-violet-50 to-cyan-50 dark:from-violet-950/20 dark:to-cyan-950/20

Icons

  • Use Lucide React icons consistently throughout the application
  • Maintain consistent sizing (e.g., h-4 w-4 for inline icons, h-6 w-6 for feature icons)
  • Use icons to enhance visual communication, not replace text

Utility Classes

Consistent Spacing

Use Tailwind's spacing utilities consistently:

  • space-y-6 for vertical spacing between components
  • gap-6 for grid and flex layouts
  • mb-6 for margin below headings and navigation elements

Typography

Follow these typography patterns:

  • Page titles: text-3xl font-bold tracking-tighter sm:text-4xl md:text-5xl
  • Section headings: text-xl font-semibold
  • Card titles: Use the <CardTitle> component
  • Body text: Default text size with text-muted-foreground for secondary text

Responsive Design

Ensure all pages are responsive:

  • Use grid layouts with responsive column counts: grid-cols-1 md:grid-cols-2 lg:grid-cols-3
  • For two-column layouts, use md:grid-cols-[2fr_1fr] to stack on mobile
  • Test all pages at mobile, tablet, and desktop breakpoints

Tool Logo Display

When displaying tool logos:

  • Use the <ToolLogo> component for consistent styling
  • Pass the appropriate toolId and size props
  • The component handles proper background and padding for each logo

Community Elements

Highlight the open-source nature of the project:

  • Include GitHub stars, license information, and contributor count
  • Add links to GitHub repository and community platforms
  • Use "Open Source" badges and callouts
  • Emphasize community contributions and collaborative learning

Cursor: AI-Assisted Development with Rules

Cursor is a powerful AI coding tool that helps automate, refactor, and document code using natural language prompts and project-specific rules. VibeCodex is designed to work seamlessly with Cursor for an AI-first workflow.

Why Cursor?

  • Enables rapid prototyping and automation of repetitive coding tasks
  • Enforces project conventions and best practices through rules
  • Makes onboarding and collaboration easier for new contributors

Writing Effective Cursor Rules

  • Use simple, specific, and focused rules tailored to your project
  • Organize rules in .cursor/rules/ as modular .mdc files (see Cursor Rules & Prompt Templates)
  • Example rule file:
# React Component Guidelines
- Use functional components with hooks
- Export as named exports
- Use Tailwind CSS for styling
- Use PascalCase for component names
  • Example prompt for Cursor:
Refactor this component to use the latest shadcn/ui Button and add error handling.

Best Practices

  • Start with 10-15 core rules and iterate based on results
  • Reference your tech stack and preferred patterns in rules
  • Keep rules up to date as your project evolves
  • See Cursor Rules & Prompt Templates for more examples and community best practices

Project Structure

The VibeCodex project follows this file structure:

vibecodex/
├── app/                    # Next.js App Router pages
│   ├── contribute/         # Contribution page
│   ├── projects/           # Projects listing and details
│   ├── start/              # Getting started page
│   ├── globals.css         # Global styles
│   ├── layout.tsx          # Root layout with metadata
│   ├── page.tsx            # Home page
│   ├── robots.ts           # Robots.txt configuration
│   └── sitemap.ts          # Sitemap configuration
├── components/             # Reusable React components
│   ├── ui/                 # UI components (shadcn/ui)
│   ├── mobile-nav.tsx      # Mobile navigation
│   ├── phase-navigation.tsx # Project phase navigation
│   ├── phase-completion-status.tsx # Phase completion UI
│   └── tool-logo.tsx       # Tool logo component
├── lib/                    # Utility functions and data
│   ├── mock-data.ts        # Mock data for projects and tools
│   ├── seo-config.ts       # SEO configuration
│   └── utils.ts            # Utility functions
├── public/                 # Static assets
│   ├── images/             # Image assets
│   └── favicon.ico         # Favicon
└── implementation-notes.md # Project documentation

Tech Stack

VibeCodex is built with the following technologies:

  • Framework: Next.js 14+ with App Router
  • Language: TypeScript
  • Styling: Tailwind CSS
  • UI Components: shadcn/ui
  • Icons: Lucide React
  • Deployment: Vercel
  • Version Control: Git/GitHub

AI Attribution

VibeCodex has been developed with assistance from the following AI systems:

  • v0 by Vercel: Contributed to the initial design, implementation, and optimization of the codebase. v0 helped with creating responsive layouts, implementing interactive components, and optimizing the site for both search engines and AI indexing.

When making contributions that involve AI assistance, please add attribution in the following format:

/**
* Component: [Component Name]
* AI Contributors:
* - [AI Name]: [Brief description of contribution]
* - [AI Name]: [Brief description of contribution]
*/

Contribution Guidelines for Vibe Contributions

When making "vibe contributions" (non-code contributions that improve the project's experience, usability, or community feel), please reference this implementation-notes.md file for guidance on the project's philosophy, design language, and component patterns.

Vibe contributions can include:

  • Feedback on user interface and experience
  • Suggestions for new features or improvements
  • Documentation improvements
  • Sharing experiences using the toolkit
  • Reporting bugs or issues
  • Creating tutorials or guides

All vibe contributions should align with the project philosophy outlined at the beginning of this document and maintain consistency with the established design language.

Development Workflow Guide

Setting Up Your Environment

  1. Clone the Repository: Use Git to clone the VibeCodex repository from GitHub.

    git clone https://github.com/vibecodex/vibecodex.git
    
  2. Install Dependencies: Navigate to the project directory and install the necessary dependencies.

    cd vibecodex
    npm install
    
  3. Run the Development Server: Start the development server to see your changes in real-time.

    npm run dev
    
  4. Code Changes: Make your code changes in the appropriate files. Follow the project structure and guidelines provided in this document.

  5. Testing: Test your changes across different screen sizes and devices to ensure responsiveness and usability.

  6. Commit Your Changes: Commit your changes with a clear and concise message.

    git commit -m "Add new feature: [Feature Name]"
    
  7. Push Your Changes: Push your changes to your forked repository on GitHub.

    git push origin main
    
  8. Create a Pull Request: Go to the VibeCodex GitHub repository and create a pull request with your changes. Reference the issue you are addressing if applicable.

  9. Review and Merge: Your changes will be reviewed by the maintainers. Once approved, they will be merged into the main repository.

Code Review Process

  • Clarity: Ensure your code is clear and easy to understand.
  • Consistency: Follow the established design language and component patterns.
  • Documentation: Update any relevant documentation to reflect your changes.
  • Testing: Include tests for any new features or bug fixes.

Deployment

  • Automated: VibeCodex uses Vercel for automated deployment. Changes merged into the main branch will be automatically deployed to the live site.
  • Manual: If you need to manually deploy, you can do so using Vercel's CLI.
    vercel --prod
    

Contribution Attribution

When making contributions, please include attribution for any AI systems used in the development process. This helps maintain transparency and acknowledges the contributions of AI systems.

/**
* Component: [Component Name]
* AI Contributors:
* - [AI Name]: [Brief description of contribution]
* - [AI Name]: [Brief description of contribution]
*/

By following these guidelines, you can contribute effectively to the VibeCodex project and help improve the AI Coding Starter Kit for beginners.

Back to Docs Index

Last updated: Recently