159 lines
5.0 KiB
Markdown
159 lines
5.0 KiB
Markdown
# Development Rules and Guidelines
|
|
|
|
## Core Principles
|
|
1. **No emojis** - Use proper icons from icon libraries (Lucide, Heroicons, etc.)
|
|
2. **Minimalist paper style** - Clean, document-focused design with clear typography
|
|
3. **Mobile-first responsive design** - Must work perfectly on all device sizes
|
|
4. **Accessibility first** - WCAG 2.1 AA compliance minimum
|
|
5. **Clear separation of concerns** - Components, composables, stores, styles all properly separated
|
|
6. **TypeScript strict mode** - No any types, proper typing throughout
|
|
|
|
## Architecture Decisions
|
|
|
|
### Tech Stack
|
|
- Vue 3 with Composition API
|
|
- TypeScript (strict mode)
|
|
- Vite for build tooling
|
|
- Vue Router for navigation
|
|
- Pinia for state management
|
|
- CSS custom properties for theming
|
|
- CSS Grid/Flexbox for layouts (no CSS framework bloat)
|
|
|
|
### Project Structure
|
|
```
|
|
src/
|
|
├── assets/ # Static assets, fonts
|
|
├── components/ # Reusable Vue components
|
|
│ ├── layout/ # Header, Footer, Navigation
|
|
│ ├── document/ # Document viewers, sections
|
|
│ └── ui/ # Buttons, cards, forms
|
|
├── composables/ # Vue composables for shared logic
|
|
├── pages/ # Route-based page components
|
|
├── router/ # Vue Router configuration
|
|
├── stores/ # Pinia stores
|
|
├── styles/ # Global styles, variables, mixins
|
|
├── types/ # TypeScript type definitions
|
|
└── utils/ # Helper functions
|
|
```
|
|
|
|
### CSS Design System
|
|
|
|
#### Color Palette
|
|
- Paper white background: `#FAFAF8`
|
|
- Off-white sections: `#F5F5F0`
|
|
- Text black: `#1A1A1A`
|
|
- Muted text: `#666666`
|
|
- Accent (links/actions): `#0066CC`
|
|
- Warning: `#D97706`
|
|
- Error: `#DC2626`
|
|
- Success: `#059669`
|
|
|
|
#### Typography
|
|
- System font stack for body
|
|
- Monospace for code/technical content
|
|
- Clear hierarchy: 1.618 golden ratio scale
|
|
- Line height: 1.6 for body, 1.2 for headings
|
|
- Maximum line length: 75ch for readability
|
|
|
|
#### Spacing
|
|
- Base unit: 8px
|
|
- Scale: 4, 8, 12, 16, 24, 32, 48, 64, 96
|
|
- Consistent padding/margins using CSS custom properties
|
|
|
|
### Component Guidelines
|
|
1. Single responsibility principle
|
|
2. Props validation with TypeScript interfaces
|
|
3. Emit events for parent communication
|
|
4. Use slots for content projection
|
|
5. Scoped styles by default
|
|
6. BEM naming for CSS classes when needed
|
|
|
|
### Content Adaptations
|
|
|
|
#### Bylaws Modifications
|
|
- Change proposal timeline from 30 days to 9-14 days
|
|
- Emphasize do-ocracy principles
|
|
- Clear delegation of authority to members
|
|
- Streamlined decision-making process
|
|
- Board as "wardens" not leaders - infrastructure and conflict resolution only
|
|
|
|
#### Key Sections to Include
|
|
1. **Home/Introduction** - Mission, purpose, adaptability notice
|
|
2. **Bylaws** - Legal structure and governance
|
|
3. **Community Standards** - Code of conduct and accountability
|
|
4. **Do-ocracy Guide** - How to get things done (based on hackerspace blueprint)
|
|
5. **Decision Making** - When to act vs when to meet
|
|
6. **Conflict Resolution** - Private talks, board mediation
|
|
7. **Membership** - How to join and participate
|
|
8. **The Board** - Limited role as infrastructure maintainers
|
|
9. **Resources** - Templates, forms, additional reading
|
|
10. **Adapt This** - Guide for other hackerspaces
|
|
|
|
#### Core Do-ocracy Principles to Highlight
|
|
- "If you want something done: Just do it!"
|
|
- Authority comes from doing, not from election
|
|
- Communicate actions to the community
|
|
- Be open to feedback and potential reversals
|
|
- Focus on execution over perfect planning
|
|
- Allow people to fail and learn
|
|
- Build mutual trust through action
|
|
|
|
### Performance Targets
|
|
- Lighthouse score > 95 all categories
|
|
- First Contentful Paint < 1.5s
|
|
- Time to Interactive < 3s
|
|
- Bundle size < 150KB (gzipped)
|
|
|
|
### Accessibility Requirements
|
|
- Semantic HTML throughout
|
|
- ARIA labels where needed
|
|
- Keyboard navigation support
|
|
- Focus management for routes
|
|
- Color contrast ratios meeting WCAG AA
|
|
- Screen reader tested
|
|
|
|
### Content Management
|
|
- Documents stored as Markdown or JSON
|
|
- Static generation where possible
|
|
- Search functionality for documents
|
|
- Print-friendly styles
|
|
- Export to PDF capability
|
|
|
|
### Testing Strategy
|
|
- Unit tests for utilities and composables
|
|
- Component testing for critical UI
|
|
- E2E tests for main user flows
|
|
- Accessibility testing with axe-core
|
|
|
|
## Implementation Notes
|
|
|
|
### Phase 1: Foundation
|
|
- Set up Vue 3 + TypeScript + Vite
|
|
- Create base layout components
|
|
- Implement routing structure
|
|
- Set up CSS design system
|
|
|
|
### Phase 2: Content
|
|
- Convert markdown documents to components
|
|
- Implement document viewer
|
|
- Add navigation between sections
|
|
- Create search functionality
|
|
|
|
### Phase 3: Polish
|
|
- Add print styles
|
|
- Implement PDF export
|
|
- Optimize performance
|
|
- Add PWA capabilities
|
|
|
|
### Phase 4: Distribution
|
|
- Documentation for adaptation
|
|
- Template generation tools
|
|
- Deployment guide
|
|
- Community contribution guidelines
|
|
|
|
## References
|
|
- Hackerspace Design Patterns: https://hackerspace.design
|
|
- Vue 3 Best Practices
|
|
- TypeScript Strict Mode Configuration
|
|
- WCAG 2.1 Guidelines
|
|
- Progressive Enhancement Principles |