Design Version Control in Team Workflows

1Git branch                          Figma version name
2feat/sprint-3/course-detail    →    Sprint 3 / Course Detail — Final
3feat/sprint-3/checkout-step-1  →    Sprint 3 / Checkout Step 1 — Final
4fix/enrollment-cta-contrast    →    Hotfix / Enrollment CTA Contrast — Final
5explore/new-card-layout        →    Explore / Card Layout — Draft (branch: never main)

1## Changes
2[describe implementation changes]
3
4## Design Reference
5- Figma file: [url]
6- Named version: Sprint N / [Component] — Final
7- Figma branch: [branch name if still active]
8
9## Design QA
10- [ ] Self-QA completed against named version
11- [ ] No open design comments in Figma
12- [ ] Token changes applied to tokens.css

1git log --oneline --grep='Figma'
2# Shows all commits that reference Figma links
3# Output:
4# a1b2c3d feat(course-detail): implement course detail (Figma: Sprint 3 Final)
5# e4f5g6h feat(checkout): implement checkout step 1 (Figma: Sprint 3 Checkout Final)

1Breaking changes (require developer action):
2  - Color value change (update CSS token or variable)
3  - Spacing change > 4px on a component in implementation
4  - Typography change (weight, size, family)
5  - Component removed or renamed
6  - New required state (developer must add new CSS/JS)
7  - Layout change that affects implemented code
8
9Non-breaking changes (no developer action needed):
10  - Content/copy changes (handled separately)
11  - New component not yet in implementation
12  - Artboard-level design exploration on non-implemented pages
13  - Annotation updates
14  - Adding a new variant that is not being implemented this sprint

1[DESIGN BREAKING CHANGE] Sprint 3 / Course Detail
2
3Component: Course Card
4Change type: Color update
5Old value: border-color: #E5E7EB (border-default token)
6New value: border-color: #D1D5DB (border-strong token)
7
8Figma: Updated in named version 'Sprint 3 / Course Detail — v1.1'
9New Figma link: [url]
10
11Developer action required:
12  .course-card { border-color: var(--color-border-strong, #d1d5db); }
13  (was: --color-border)
14
15Reason for change: Higher contrast on light background pages
16  per Stark accessibility audit result.
17
18Impacted: CourseCard component only
19Timeline: Please update before Thursday QA
20
21@developer-name

1Sprint | Date       | Component        | Change            | Dev Action
2-------|------------|------------------|-------------------|-----------
3S3     | 2026-06-03 | Course Card      | Border color      | CSS token update
4S3     | 2026-06-05 | Lesson Item      | Height 72→64px    | CSS height update
5S3     | 2026-06-06 | Enrollment bar   | Shadow opacity    | CSS shadow update

1## v3.2.0 — 2026-06-14 (Sprint 3 complete)
2### Added
3- Category badge: gray variant (data-cat='general')
4  CSS: .course-badge[data-cat='general'] { bg: #f3f4f6; color: #4b5563 }
5- Enrollment bar: sticky enrollment CTA for all course pages
6  Implementation: see EnrollmentBar.tsx
7
8### Changed  
9- Course card border: border-default (#E5E7EB) → border-strong (#D1D5DB)
10  Dev action: update .course-card border-color variable reference
11- Lesson item height: 72px → 64px
12  Dev action: .lesson-item { height: 4rem; }
13
14### Fixed
15- Enrollment bar shadow: opacity corrected from 0.12 to 0.08
16
17## v3.1.0 — 2026-05-28 (Sprint 2 complete)
18### Added
19- Lesson item: progress indicator (checkmark for complete, circle for incomplete)
20...

1// scripts/generate-changelog.js
2// Compares current token values with previous version
3// Outputs markdown changelog for token changes
4const previous = require('./tokens/v3.1.json');
5const current = require('./tokens/v3.2.json');
6
7function diff(prev, curr, path = '') {
8  const changes = [];
9  for (const [key, val] of Object.entries(curr)) {
10    const fullPath = path ? `${path}.${key}` : key;
11    if (typeof val === 'object' && val.value) {
12      if (prev[key]?.value !== val.value) {
13        changes.push({ path: fullPath, old: prev[key]?.value, new: val.value });
14      }
15    } else if (typeof val === 'object') {
16      changes.push(...diff(prev[key] || {}, val, fullPath));
17    }
18  }
19  return changes;
20}
21
22const changes = diff(previous, current);
23console.log('## Token Changes');
24changes.forEach(c => {
25  console.log(`- ${c.path}: ${c.old} → ${c.new}`);
26});

1# Find the commit where the breaking change was applied
2git log --oneline -20
3# output: a1b2c3d 'fix(tokens): update course-card border to border-strong'
4
5# Revert the specific commit
6git revert a1b2c3d
7# Creates a new commit that undoes the change
8
9# Or: if the change is in a token file, simply revert the value
10# tokens.css: --color-border-card: #e5e7eb;  (back to original)

1[DESIGN ROLLBACK] Sprint 3 / Course Card border
2
3We are reverting the border-color change from v1.1.
4
5Reason: The #D1D5DB border caused a contrast failure on the
6  marketing-blue section backgrounds that we missed in QA.
7  Reverting to #E5E7EB which passes contrast on all backgrounds.
8
9Design version: Now on Sprint 3 / Course Detail — Rollback to v1.0
10Figma link updated: [url]
11
12Developer action:
13  Revert .course-card border-color to var(--color-border, #e5e7eb)
14  (was temporarily changed to var(--color-border-strong, #d1d5db))
15
16No other changes. Token --color-border-strong remains in system
17for future use on non-blue backgrounds.
18
19@developer-name