Module 28: Infrastructure & Organization — Design & Code Foundations

09

undefined

File Types

Print

PSD, AI, INDD

Proprietary formats

Native design app files

Web

HTML, CSS, JS

Open formats

Text-based, version controllable

Asset Management

Print

Package files

Include all assets

Bundle for handoff

Web

Optimize & serve

Performance matters

Compression, CDN, lazy load

Reusability

Print

Master pages

Document level

Templates within documents

Web

Components

Cross-project

Shared across entire system

Collaboration

Print

File sharing

Check out/in

One person edits at a time

Web

Git branches

Parallel work

Multiple simultaneous edits

10

undefined

Cognitive Load

undefined

Communication Overhead

undefined

Consistency Value

undefined

11

Organization in Practice

How teams organize design projects effectively.

Monorepo Structure

Shared packages + apps

Principles Identified:

Shared packages Design system used across apps

Consistent tooling Same build process everywhere

Clear boundaries Apps vs packages separated

Key insight: Vercel's monorepo lets teams share code while maintaining clear ownership boundaries.

Design System

Components + tokens + docs

Principles Identified:

Design tokens Shared values across design and code

Component docs Usage examples for every component

Governance Clear process for contributions

Key insight: Polaris documents not just what components look like, but when and how to use them.

Design Language System

Sketch to React

Principles Identified:

Single source Design files generate code

Automation Components sync automatically

Consistency Design and code always match

Key insight: Airbnb automated the design-to-code pipeline so components stay synchronized.

12

Organization Mistakes

Common errors in project organization.

Failure: No Naming Convention

final-v2.psd
FINAL_FINAL.psd
new folder/asdf.jpg

No one can find anything

Fix: Establish and document standards

homepage-hero-v2.psd
product-card.psd
assets/images/team-jane.jpg

Predictable, findable

Rule: Pick a naming convention, document it, enforce it. kebab-case, lowercase, no spaces.

Failure: Flat File Structure

project/
├── file1.css
├── file2.css
├── img1.jpg
├── img2.jpg
└── ... (100 more)

Fix: Organize by type or feature

project/
├── styles/
├── images/
├── components/
└── pages/

Rule: Group related files in folders. Organize by type or by feature—pick one and be consistent.

Failure: No Documentation

"Ask Sarah, she knows"

Knowledge locked in heads

Fix: Document decisions and processes

README.md explains setup

DECISIONS.md explains why

Anyone can onboard

Rule: Write it down. READMEs, style guides, decision logs. Documentation scales, asking people doesn't.

Failure: Premature Optimization

Complex system for 2-person team

Overhead exceeds benefit

Fix: Add structure to solve problems

Start simple

Add structure when needed

Right-sized for team

Rule: Don't over-engineer. Add structure to solve real problems, not hypothetical ones.

13

Organization Assessment

Evaluate your project organization.

01

5-Minute Onboarding

Tests: Discoverability

Can a new team member understand your file structure in 5 minutes? If not, you need better organization or documentation.

☑ Clear README

☑ Obvious structure

☑ Consistent naming

02

Find-a-File Test

Tests: Predictability

Pick a random asset. Can you find it in under 10 seconds? Can someone unfamiliar with the project find it? If not, reorganize or add better naming.

"Find the login button styles"

< 10 seconds = pass

03

Bus Factor

Tests: Knowledge sharing

If the person who set this up left, could others continue? Is critical knowledge documented, or locked in one person's head?

☑ Setup steps documented

☑ Decisions explained

☑ No single point of failure

04

Consistency Audit

Tests: Pattern adherence

Look at 10 random files. Do they follow the same naming convention? Same structure? Inconsistency reveals where standards aren't enforced.

☑ Naming consistent

☑ Structure consistent

☑ Patterns followed

14

Project Structure Templates

Starter structures for different project sizes.

project/
├── index.html
├── styles/
│   ├── main.css
│   └── components.css
├── scripts/
│   └── main.js
├── images/
│   ├── hero.jpg
│   └── icons/
└── README.md

Small Project via CSS

Flat structure - Simple, easy to navigate
By file type - Styles, scripts, images
README - Minimal documentation

Tip: Start here. Add complexity only when you need it.

project/
├── src/
│   ├── components/
│   │   ├── Button/
│   │   │   ├── Button.js
│   │   │   ├── Button.css
│   │   │   └── Button.test.js
│   │   └── Card/
│   ├── pages/
│   ├── styles/
│   │   ├── base/
│   │   ├── tokens/
│   │   └── utilities/
│   └── utils/
├── public/
│   └── images/
├── docs/
└── README.md

Medium Project via CSS

Component folders - Code + styles + tests together
Separated concerns - Base, tokens, utilities
docs folder - More documentation

Tip: Component-based organization scales better for teams.

/* tokens/colors.css */
:root {
  /* Brand */
  --color-brand-primary: #3b82f6;
  --color-brand-secondary: #10b981;

  /* Semantic */
  --color-text-primary: #1f2937;
  --color-text-secondary: #6b7280;
  --color-bg-primary: #ffffff;
  --color-bg-secondary: #f9fafb;

  /* Feedback */
  --color-success: #10b981;
  --color-error: #ef4444;
  --color-warning: #f59e0b;
}

Design Tokens via CSS

Semantic names - Purpose, not appearance
Grouped by use - Brand, semantic, feedback
Single source - Change once, update everywhere

Tip: Design tokens bridge design and code. Export from Figma, use in CSS.

# Project Name

## Quick Start
```
npm install
npm run dev
```

## File Structure
- `/src/components` - Reusable UI components
- `/src/pages` - Page templates
- `/src/styles` - Global styles and tokens

## Naming Conventions
- Files: `kebab-case.js`
- Components: `PascalCase`
- CSS classes: `kebab-case`

## Contributing
1. Create branch: `feature/description`
2. Make changes
3. Open PR

README Template via CSS

Quick start - Get running fast
Structure explained - Where things go
Conventions - How to name things

Tip: A good README is the best onboarding document.

15

Self-Assessment

Test your understanding of project organization.

Q1

What's the difference between components and templates?

Click to reveal

Q2

When should you add more organizational structure?

Click to reveal

Q3

What should a project README contain?

Click to reveal

Q4

How do organizational needs change with team size?

Click to reveal

Q5

What are design tokens and why use them?

Click to reveal

Infrastructure & Organization

Print vs Web

undefined

Science & Psychology

undefined

Real-World Examples

Organization in Practice

Common Failures

Organization Mistakes

Visual Tests

Organization Assessment

5-Minute Onboarding

Find-a-File Test

Bus Factor

Consistency Audit

CSS Implementation

Project Structure Templates

Self-Assessment

Self-Assessment

Key Takeaways