Skip to content

Project Organization Principles

When to Use

Use this when starting a design system → Bootstrap mapping project to organize analysis, documentation, and implementation files systematically.

Universal Project Structure

[project_name]/
├── project-notes.md                         # Project overview and status
├── design-system-analysis/                  # Complete design system documentation
│   ├── design-system-inventory.md           # Complete inventory
│   ├── color-system-analysis.md             # Color system
│   ├── typography-system-analysis.md        # Typography
│   ├── spacing-system-analysis.md           # Spacing
│   ├── border-radius-analysis.md            # Border and radius
│   ├── shadow-elevation-analysis.md         # Shadow and elevation
│   └── advanced-features-analysis.md        # CREATE category features
├── bootstrap-mapping/                       # Bootstrap mapping documentation
│   ├── bootstrap-variable-inventory.md      # What Bootstrap provides
│   ├── direct-mapping-plan.md               # Direct design→Bootstrap mappings
│   ├── custom-variables-plan.md             # Justified custom variables
│   ├── extension-plan.md                    # EXTEND category
│   └── implementation-strategy.md           # Implementation approach
├── component-impact-analysis/               # How personalization affects components
│   ├── button-components-impact.md          # Button system
│   ├── form-components-impact.md            # Form system
│   ├── navigation-components-impact.md      # Navigation
│   └── layout-components-impact.md          # Layout
└── final-implementation/                    # Ready-for-implementation files
    ├── variable-overrides.scss              # Bootstrap variable overrides
    ├── bootstrap-extensions.scss            # EXTEND category additions
    ├── custom-variables.scss                # CUSTOMIZE category variables
    ├── advanced-features/                   # CREATE category (if needed)
    │   ├── _advanced-mixins.scss
    │   └── _advanced-utilities.scss
    ├── implementation-guide.md              # Step-by-step implementation
    └── validation-checklist.md              # Testing and validation

Progressive Documentation Approach

Step Action Goal
1 Process each design system aspect incrementally One category at a time
2 Update consolidated documentation progressively Build complete picture
3 Build complete mapping strategy before implementation No code until analysis complete
4 Present final implementation plan for approval Stakeholder review before execution

Phase-Based Implementation Process

Phase 1: System Inventory (Document-First)

  1. Create project folder structure
  2. Process each design system aspect incrementally
  3. Update consolidated analysis progressively
  4. Build complete inventory before mapping

Phase 2: Bootstrap Assessment

  1. Document Bootstrap capabilities systematically
  2. Identify direct mapping opportunities (ACCOMMODATE)
  3. Justify custom variable needs (CUSTOMIZE/CREATE)
  4. Plan implementation strategy

Phase 3: Component Impact Planning

  1. Analyze how personalization affects components
  2. Plan component-specific customizations
  3. Prioritize implementation order
  4. Validate approach with stakeholders

Phase 4: Implementation Preparation

  1. Generate final SCSS files
  2. Create implementation guide
  3. Prepare validation checklist
  4. Present complete plan for approval

Decision Table: When to Use Each Folder

If you need to... Use folder... Why
Document what design system provides design-system-analysis/ Complete inventory before mapping
Plan Bootstrap mappings bootstrap-mapping/ Strategy before implementation
Analyze component changes component-impact-analysis/ Understand downstream effects
Store final SCSS files final-implementation/ Ready-to-integrate code

Common Mistakes

  • Wrong: Starting implementation before completing analysis → Right: Complete all analysis phases first
  • Wrong: Mixing analysis and implementation files → Right: Separate analysis from code
  • Wrong: Skipping component impact analysis → Right: Always analyze downstream effects
  • Wrong: Creating SCSS files without approval → Right: Present strategy for review first

See Also