Skip to content

Commit 63dc800

Browse files
Meatball1601Meatball1601
committed
More documentation updates
1 parent cbcded0 commit 63dc800

6 files changed

Lines changed: 725 additions & 74 deletions

File tree

‎docs/components.md‎

Lines changed: 145 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,20 +3,154 @@
33
This guide explains the structure and usage of React components in the Open Hardware Initiative website.
44

55
## Component Structure
6-
- Where components live (`src/components/`)
7-
- Naming conventions
8-
- UI vs. page components
6+
7+
### Directory Organization
8+
```
9+
src/components/
10+
├── ui/ # Reusable UI components (shadcn/ui)
11+
│ ├── button.tsx # Button component
12+
│ ├── card.tsx # Card component
13+
│ ├── dialog.tsx # Modal dialogs
14+
│ └── ... # Other UI primitives
15+
├── HeroSection.tsx # Landing page hero
16+
├── Navbar.tsx # Navigation bar
17+
├── Footer.tsx # Site footer
18+
├── TeamSection.tsx # Team display
19+
├── ProjectCard.tsx # Individual project card
20+
├── EventCard.tsx # Individual event card
21+
└── ... # Other page-specific components
22+
```
23+
24+
### Component Types
25+
- **UI Components** (`ui/`) - Reusable, generic components (buttons, cards, etc.)
26+
- **Page Components** (`pages/`) - Full page layouts
27+
- **Section Components** - Major page sections (hero, team, projects)
28+
- **Card Components** - Individual item displays (team member, project, event)
29+
30+
## Key Components
31+
32+
### Navigation
33+
- **Navbar** - Main navigation with mobile menu
34+
- **DesktopNavigation** - Desktop navigation bar
35+
- **MobileNavigation** - Mobile hamburger menu
36+
37+
### Content Sections
38+
- **HeroSection** - Landing page hero with call-to-action
39+
- **TeamSection** - Team member grid display
40+
- **ProjectCard** - Individual project showcase
41+
- **EventCard** - Individual event display
42+
- **SponsorSection** - Sponsor logos and information
43+
44+
### UI Elements
45+
- **Button** - Primary, secondary, and ghost button variants
46+
- **Card** - Content containers with headers and bodies
47+
- **Dialog** - Modal popups for forms and confirmations
48+
- **Badge** - Status indicators and tags
49+
50+
## Component Patterns
51+
52+
### Props Interface
53+
```typescript
54+
interface ComponentProps {
55+
title: string;
56+
description?: string;
57+
className?: string;
58+
children?: React.ReactNode;
59+
}
60+
```
61+
62+
### Styling with Tailwind
63+
```typescript
64+
// Use Tailwind classes for styling
65+
<div className="flex flex-col space-y-4 p-6 bg-white rounded-lg shadow-md">
66+
<h2 className="text-2xl font-bold text-gray-900">{title}</h2>
67+
<p className="text-gray-600">{description}</p>
68+
</div>
69+
```
70+
71+
### Responsive Design
72+
```typescript
73+
// Mobile-first responsive classes
74+
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
75+
{/* Content adapts to screen size */}
76+
</div>
77+
```
978

1079
## Best Practices
11-
- Reusability
12-
- Props and typing
13-
- Styling with Tailwind
1480

15-
## TODO
16-
- Add examples of component usage
17-
- Document key components and their props
18-
- Add a diagram of component hierarchy
81+
### Component Design
82+
- **Single Responsibility** - Each component has one clear purpose
83+
- **Reusability** - UI components should be generic and reusable
84+
- **Props Interface** - Always define TypeScript interfaces for props
85+
- **Default Props** - Provide sensible defaults where appropriate
86+
87+
### Styling Guidelines
88+
- **Tailwind First** - Use Tailwind classes for most styling
89+
- **Component Variants** - Use class-variance-authority for component variants
90+
- **Consistent Spacing** - Follow Tailwind spacing scale
91+
- **Accessibility** - Include proper ARIA labels and semantic HTML
92+
93+
### Performance
94+
- **Memoization** - Use React.memo for expensive components
95+
- **Lazy Loading** - Lazy load components that aren't immediately visible
96+
- **Image Optimization** - Use proper image formats and sizes
97+
98+
## Common Patterns
99+
100+
### Conditional Rendering
101+
```typescript
102+
{isOpen && <ApplicationForm />}
103+
{status === 'loading' ? <Spinner /> : <Content />}
104+
```
105+
106+
### List Rendering
107+
```typescript
108+
{teamMembers.map((member) => (
109+
<TeamMemberCard key={member.id} member={member} />
110+
))}
111+
```
112+
113+
### Event Handling
114+
```typescript
115+
const handleClick = (event: React.MouseEvent) => {
116+
event.preventDefault();
117+
// Handle click logic
118+
};
119+
```
120+
121+
## Adding New Components
122+
123+
### 1. Create Component File
124+
```typescript
125+
// src/components/NewComponent.tsx
126+
import React from 'react';
127+
128+
interface NewComponentProps {
129+
title: string;
130+
// Add other props
131+
}
132+
133+
export const NewComponent: React.FC<NewComponentProps> = ({ title }) => {
134+
return (
135+
<div className="p-4 bg-white rounded-lg">
136+
<h3 className="text-lg font-semibold">{title}</h3>
137+
</div>
138+
);
139+
};
140+
```
141+
142+
### 2. Export from Index (if needed)
143+
```typescript
144+
// src/components/index.ts
145+
export { NewComponent } from './NewComponent';
146+
```
147+
148+
### 3. Import and Use
149+
```typescript
150+
import { NewComponent } from '@/components/NewComponent';
151+
```
19152

20153
---
21154

22-
*Contributions welcome! Add examples and explanations for new contributors.*
155+
**Last Updated**: December 2024
156+
**Maintained by**: Open Hardware Initiative Development Team

‎docs/development.md‎

Lines changed: 157 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,22 +2,166 @@
22

33
This guide explains how to set up and work on the Open Hardware Initiative website as a developer.
44

5+
## Prerequisites
6+
7+
### Required Software
8+
- **Git** - [Download here](https://git-scm.com/)
9+
- **Bun** (recommended) - [Download here](https://bun.sh/)
10+
- **Node.js 18+** (alternative) - [Download here](https://nodejs.org/)
11+
- **Code Editor** - VS Code, Sublime Text, etc.
12+
13+
### Recommended Extensions (VS Code)
14+
- **TypeScript and JavaScript Language Features**
15+
- **Tailwind CSS IntelliSense**
16+
- **ESLint**
17+
- **Prettier**
18+
- **GitHub Copilot** - AI coding assistant (highly recommended!)
19+
520
## Local Setup
6-
- Prerequisites (Bun, Node.js, Git)
7-
- Cloning the repo
8-
- Installing dependencies
9-
- Running the dev server
1021

11-
## Workflow
12-
- Branching strategy
13-
- Commit message guidelines
14-
- Code review process
22+
### 1. Clone the Repository
23+
```bash
24+
git clone https://github.com/OpenHardware-Initiative/OpenHardware-Initiative.github.io.git
25+
cd OpenHardware-Initiative.github.io
26+
```
27+
28+
### 2. Install Dependencies
29+
```bash
30+
cd "Source code"
31+
bun install
32+
```
33+
34+
### 3. Start Development Server
35+
```bash
36+
bun run dev
37+
```
38+
39+
The site will be available at **http://localhost:8080**
40+
41+
## Development Workflow
42+
43+
### Making Changes
44+
1. **Create a feature branch** (optional for small changes)
45+
```bash
46+
git checkout -b feature/your-feature-name
47+
```
48+
49+
2. **Make your changes** in the code
50+
3. **Test locally** - Check the browser for your changes
51+
4. **Commit your changes**
52+
```bash
53+
git add .
54+
git commit -m "Add feature: brief description"
55+
```
56+
57+
5. **Push to main branch**
58+
```bash
59+
git push origin main
60+
```
61+
62+
### Code Quality
63+
- **Lint your code**: `bun run lint`
64+
- **Check TypeScript errors** in your editor
65+
- **Test on different screen sizes** (mobile, tablet, desktop)
66+
67+
## Development Tips
68+
69+
### Using GitHub Copilot
70+
GitHub Copilot is excellent for this project! It can help with:
71+
- **Component generation** - "Create a React component for a team member card"
72+
- **Tailwind classes** - "Add responsive grid layout with 3 columns on desktop"
73+
- **TypeScript interfaces** - "Create interface for project data"
74+
- **Common patterns** - "Add conditional rendering for loading state"
75+
76+
**Pro tip**: Be specific in your prompts for better results!
77+
78+
### Hot Reload
79+
- Save any file to see changes immediately
80+
- Browser automatically refreshes
81+
- No need to restart the dev server
1582

16-
## TODO
17-
- Add screenshots of local dev environment
18-
- Document advanced dev workflows (linting, testing, etc.)
19-
- Add tips for debugging and troubleshooting
83+
### Debugging
84+
- **Browser DevTools** - Check console for errors
85+
- **React DevTools** - Inspect component state
86+
- **Network tab** - Check for failed requests
87+
- **Vite error overlay** - Shows build errors in browser
88+
89+
### Common Commands
90+
```bash
91+
bun run dev # Start development server
92+
bun run build # Build for production
93+
bun run preview # Preview production build
94+
bun run lint # Check code quality
95+
```
96+
97+
## File Structure for Development
98+
99+
### Key Directories
100+
```
101+
src/
102+
├── components/ # React components
103+
├── pages/ # Page components
104+
├── data/ # Content data (edit these!)
105+
├── config/ # Configuration files
106+
├── hooks/ # Custom React hooks
107+
├── utils/ # Utility functions
108+
└── lib/ # Third-party library configs
109+
```
110+
111+
### Where to Make Changes
112+
- **Content**: `src/data/` files
113+
- **Components**: `src/components/`
114+
- **Pages**: `src/pages/`
115+
- **Styling**: Tailwind classes in components
116+
- **Configuration**: `src/config/` files
117+
118+
## Best Practices
119+
120+
### Code Style
121+
- **Use TypeScript** for all new code
122+
- **Follow existing patterns** in the codebase
123+
- **Use meaningful variable names**
124+
- **Add comments** for complex logic
125+
126+
### Git Workflow
127+
- **Small, focused commits** - One change per commit
128+
- **Descriptive commit messages** - "Add team member: John Doe"
129+
- **Test before pushing** - Always test locally first
130+
131+
### Performance
132+
- **Optimize images** before adding to public/
133+
- **Use lazy loading** for heavy components
134+
- **Check bundle size** with `bun run build`
135+
136+
## Troubleshooting
137+
138+
### Common Issues
139+
- **Port 8080 in use**: Change port in `vite.config.ts` or kill the process
140+
- **Build errors**: Run `bun run lint` to see TypeScript errors
141+
- **Dependencies missing**: Run `bun install` to reinstall
142+
143+
### Getting Help
144+
- Check the [troubleshooting guide](troubleshooting.md)
145+
- Look at existing code for patterns
146+
- Use GitHub Copilot for guidance
147+
- Create an issue in the repository
148+
149+
## Deployment
150+
151+
### Automatic Deployment
152+
- **Push to main** → GitHub Actions builds and deploys
153+
- **No manual steps** required
154+
- **Site updates** in 2-3 minutes
155+
156+
### Manual Build (if needed)
157+
```bash
158+
bun run build
159+
bun run preview
160+
```
20161

21162
---
22163

23-
*Contributions welcome! Add your tips and best practices for development.*
164+
**Pro Tip**: GitHub Copilot is incredibly helpful for this React/TypeScript/Tailwind stack. It understands the project structure and can generate code that follows existing patterns!
165+
166+
**Last Updated**: December 2024
167+
**Maintained by**: Open Hardware Initiative Development Team

0 commit comments

Comments
 (0)