reference / implementation-notes
Implementation Notes for AI Coding Starter Kit
See also: Architecture Overview, Getting Started, Glossary, Roadmap, FAQ
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 widthmx-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 componentsgap-6
for grid and flex layoutsmb-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
andsize
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
-
Clone the Repository: Use Git to clone the VibeCodex repository from GitHub.
git clone https://github.com/vibecodex/vibecodex.git
-
Install Dependencies: Navigate to the project directory and install the necessary dependencies.
cd vibecodex npm install
-
Run the Development Server: Start the development server to see your changes in real-time.
npm run dev
-
Code Changes: Make your code changes in the appropriate files. Follow the project structure and guidelines provided in this document.
-
Testing: Test your changes across different screen sizes and devices to ensure responsiveness and usability.
-
Commit Your Changes: Commit your changes with a clear and concise message.
git commit -m "Add new feature: [Feature Name]"
-
Push Your Changes: Push your changes to your forked repository on GitHub.
git push origin main
-
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.
-
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.