hackerspace-governance-in-a-box/DEVELOPMENT_RULES.md

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