1  # Frontend Local Development Guide
  2  
  3  ## Design System Dependency
  4  
  5  All ACDC frontend applications depend on `@acdc/design` for shared components, tokens, and styles. In CI, this is handled automatically. For local development, you need to set up the design system manually.
  6  
  7  ## Affected Repositories
  8  
  9  - acdc-governor
 10  - acdc-scanner
 11  - acdc-messenger
 12  - acdc-wallet (React Native - uses local tokens file)
 13  
 14  ## Initial Setup
 15  
 16  ### 1. Clone the Design System
 17  
 18  ```bash
 19  # From your working-repos directory
 20  git clone https://source.ac-dc.network/alpha-delta-network/acdc-design.git
 21  cd acdc-design
 22  npm ci
 23  npm run build
 24  ```
 25  
 26  ### 2. Clone Your Target App
 27  
 28  ```bash
 29  cd ..
 30  git clone https://source.ac-dc.network/alpha-delta-network/acdc-governor.git
 31  cd acdc-governor
 32  npm install
 33  npm run dev
 34  ```
 35  
 36  The apps expect `acdc-design` to be a sibling directory:
 37  ```
 38  working-repos/
 39  ├── acdc-design/      # Design system (must be built)
 40  ├── acdc-governor/    # Governor console
 41  ├── acdc-scanner/     # Block explorer
 42  ├── acdc-messenger/   # Messenger app
 43  └── ...
 44  ```
 45  
 46  ## Keeping Design System Updated
 47  
 48  ### Quick Update Command
 49  
 50  From any frontend app directory:
 51  
 52  ```bash
 53  cd ../acdc-design && git pull && npm run build && cd -
 54  ```
 55  
 56  ### Using the Helper Script
 57  
 58  Frontend repos include an update script:
 59  
 60  ```bash
 61  ./scripts/update-design.sh
 62  ```
 63  
 64  ### When to Update
 65  
 66  | Scenario | Action |
 67  |----------|--------|
 68  | After `git pull` on the frontend app | Update design system |
 69  | Design-related TypeScript errors | Rebuild design system |
 70  | New tokens/components needed | Pull and rebuild |
 71  | Before submitting PR | Update to match CI |
 72  | CI passes, local fails | Update design system |
 73  
 74  ## How CI Handles This
 75  
 76  CI workflows automatically:
 77  
 78  1. Clone `acdc-design` fresh from main
 79  2. Run `npm ci && npm run build`
 80  3. Then install the frontend app dependencies
 81  
 82  This ensures CI always tests against the latest design system. Your local environment may lag behind if you haven't updated recently.
 83  
 84  ## React Native Apps (acdc-wallet, acdc-messenger)
 85  
 86  React Native apps can't use `file:` npm references directly. Instead, they:
 87  
 88  1. Have a local `src/theme/designTokens.ts` file
 89  2. Import colors/tokens from this local file
 90  3. The local file mirrors `@acdc/design` tokens
 91  
 92  When design tokens change, these files need manual sync. The CI clones and builds acdc-design but the React Native apps import from their local token files.
 93  
 94  ## Troubleshooting
 95  
 96  ### "Cannot find module '@acdc/design'"
 97  
 98  ```bash
 99  # Clone and build the design system
100  cd ..
101  git clone https://source.ac-dc.network/alpha-delta-network/acdc-design.git
102  cd acdc-design && npm ci && npm run build
103  cd ../your-app && npm install
104  ```
105  
106  ### TypeScript errors after update
107  
108  ```bash
109  # Rebuild the design system
110  cd ../acdc-design && npm run build && cd -
111  # Restart your dev server
112  ```
113  
114  ### Stale styles/components
115  
116  ```bash
117  # Full refresh
118  cd ../acdc-design
119  git pull
120  npm ci
121  npm run build
122  cd -
123  # Restart dev server
124  ```
125  
126  ### CI passes but local fails
127  
128  Your local acdc-design is outdated:
129  
130  ```bash
131  cd ../acdc-design && git pull && npm run build && cd -
132  ```
133  
134  ## Adding the Update Script to Other Repos
135  
136  Copy this script to `scripts/update-design.sh`:
137  
138  ```bash
139  #!/usr/bin/env bash
140  set -e
141  
142  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
143  PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
144  DESIGN_DIR="$PROJECT_DIR/../acdc-design"
145  
146  echo "Updating @acdc/design..."
147  
148  if [ ! -d "$DESIGN_DIR" ]; then
149      echo "Cloning acdc-design..."
150      git clone --depth 1 https://source.ac-dc.network/alpha-delta-network/acdc-design.git "$DESIGN_DIR"
151  fi
152  
153  cd "$DESIGN_DIR"
154  git fetch origin main
155  git reset --hard origin/main
156  npm ci
157  npm run build
158  
159  echo "Done! Updated to $(git rev-parse --short HEAD)"
160  ```
161  
162  Make executable: `chmod +x scripts/update-design.sh`