@designcrowd/fe-shared-lib 1.6.10-voiceText-1 → 1.7.0-eng-4159

package/docs/plans/DY-957-plan-phase-2-fe-shared-lib.md

@@ -1,382 +1,382 @@
-# DY-957 Phase 2: fe-shared-lib Wizard Changes
-
-## Goal
-
-Add an optional keywords step to the BYO upload wizard in `@designcrowd/fe-shared-lib`. The step fetches AI keyword suggestions, displays them in an editable textbox, and emits the keywords for the consumer to use. The step is opt-in via a `showKeywordsStep` prop (default `false`).
-
-## Repo
-
-`fe-shared-lib`
-
-## Prerequisites
-
-- Phase 1 backend endpoint deployed (needed for integration testing, not for Storybook development)
-
-## Implementation Decisions (Confirmed)
-
-- The keyword suggestions endpoint path is `/api/ai-keyword-suggestion` (this is intentionally **not** maker-prefixed).
-- `templateType` is required end-to-end; consumers must pass a non-null default value.
-- Continue action in the keywords step must be disabled while suggestions are loading.
-- Storybook coverage for `LogoKeywords` is required for this task (not optional).
-- Publishing/version bump and final validation are human-owned follow-up steps, not coding-agent scope.
-
----
-
-## Tasks
-
-### 1. Add API constant
-
-**File**: `src/experiences/constants/api.js`
-
-Add one line to the exported object:
-
-```js
-KEYWORD_SUGGESTIONS_API_URL: '/api/ai-keyword-suggestion',
-```
-
-### 2. Add `getKeywordSuggestionsAsync` to API client
-
-**File**: `src/experiences/clients/brand-crowd-api.client.js`
-
-Add a new async method following the `searchDomainNamesByKeywordAsync` pattern (lines 71-117):
-
-```js
-const getKeywordSuggestionsAsync = async ({ businessName, templateType }) => {
-  try {
-    const url = `${API.KEYWORD_SUGGESTIONS_API_URL}?businessName=${encodeURIComponent(businessName)}&templateType=${encodeURIComponent(templateType)}`;
-    const response = await getAxios()({
-      method: 'get',
-      url,
-    });
-    return response.data;
-  } catch (error) {
-    return false;
-  }
-};
-```
-
-Behavior note: if `businessName` is empty, still call the endpoint with `businessName=` and continue normally (expected to return empty suggestions).
-
-Add `getKeywordSuggestionsAsync` to the default export object (lines 119-124).
-
-### 3. Create `LogoKeywords.vue` component
-
-**File**: Create `src/experiences/components/UploadYourLogoOnBoarding/LogoKeywords.vue`
-
-Clone the structure from `LogoBusinessText.vue` (same directory). The component should:
-
-**Props:**
-- `progressLabel` (String, required) — "Step X of Y"
-- `eventCategory` (String, required) — for analytics tracking
-- `savedKeywords` (String, optional, default: `null`) — restored keywords if user navigated back then forward
-- `businessName` (String, optional, default: `''`) — from previous step (may be empty)
-- `templateType` (String, required) — e.g. "business card"
-
-Behavior note: keep current wizard behavior where empty business name is allowed; do not block navigation if no business name is entered.
-
-**Data:**
-- `keywordsText: ''` — the editable comma-separated keywords string
-- `isLoading: false`
-
-**Mounted lifecycle:**
-```js
-async mounted() {
-  if (this.savedKeywords !== null) {
-    this.keywordsText = this.savedKeywords;
-    return;
-  }
-  this.isLoading = true;
-  try {
-    const result = await brandCrowdClient.getKeywordSuggestionsAsync({
-      businessName: this.businessName,
-      templateType: this.templateType,
-    });
-    if (result && result.keywords && result.keywords.length > 0) {
-      this.keywordsText = result.keywords.join(', ');
-    }
-  } catch {
-    // leave keywordsText as empty string
-  } finally {
-    this.isLoading = false;
-  }
-},
-```
-
-**Methods:**
-- `back()` — emits `on-go-back`
-- `save()` — no-op if `isLoading` is true; otherwise tracks event with `eventAction: 'keywords'`, `eventLabel: 'Clicked_Continue'`, then emits `on-save` with `{ keywords: this.keywordsText }`
-- `onKeywordsKeyUp(e)` — if `e.key === 'Enter'` and `!isLoading`, call `this.save()`
-
-**Template:** Mirror `LogoBusinessText.vue` layout:
-- Progress label header: `{{ progressLabel }}`
-- Heading: `{{ uploadYourLogoTr('keywords') }}`
-- Description: `{{ uploadYourLogoTr('keywordsDescription') }}`
-- Single `<input>` or `<textarea>` bound to `keywordsText`, disabled while `isLoading`, with `@keyup="onKeywordsKeyUp"`
-- Show a loading indicator (spinner or skeleton) when `isLoading` is true
-- Footer with Back button (emits `on-go-back`) and Continue button (calls `save()`)
-- Continue button must be disabled while `isLoading` is `true`
-
-**i18n:** Use the `uploadYourLogoTr` mixin (same as `LogoBusinessText.vue`).
-
-### 4. Add i18n translation keys
-
-**Files**: All 7 locale files in `src/experiences/components/UploadYourLogoOnBoarding/i18n/`
-
-Add two new keys inside the `"uploadYourLogo"` object in **every** locale file, using the **English text** in all of them:
-
-```json
-"keywords": "Keywords",
-"keywordsDescription": "Add keywords related to your business and logo"
-```
-
-Add this identical English text to:
-- `upload-your-logo.json` (English)
-- `upload-your-logo.de-DE.json`
-- `upload-your-logo.es-ES.json`
-- `upload-your-logo.fr-CA.json`
-- `upload-your-logo.fr-FR.json`
-- `upload-your-logo.pt-BR.json`
-- `upload-your-logo.pt-PT.json`
-
-**Do not translate** — a separate process will sweep the codebase and replace the English placeholders with proper translations.
-
-After editing all files, run `npm run bundle-translation` to regenerate bundled translation files.
-
-### 5. Update `UploadYourLogoOnBoarding.vue` orchestrator
-
-**File**: `src/experiences/components/UploadYourLogoOnBoarding/UploadYourLogoOnBoarding.vue`
-
-#### 5a. Add new props (after existing props at lines 115-136)
-
-```js
-showKeywordsStep: {
-  type: Boolean,
-  required: false,
-  default: false,
-},
-templateType: {
-  type: String,
-  required: true,
-},
-```
-
-Note: `templateType` must be provided by the consumer (fallback/defaulting happens in consumer app config, not in this component).
-
-#### 5b. Update `data()` (lines 142-154)
-
-Change `totalNumSteps` to be dynamic:
-```js
-totalNumSteps: this.useDropzone
-  ? (this.showKeywordsStep ? 6 : 5)
-  : (this.showKeywordsStep ? 5 : 4),
-```
-
-Add new data property:
-```js
-savedKeywords: null,
-```
-
-#### 5c. Add computed property for brand colours step number
-
-```js
-brandColoursStep() {
-  return this.showKeywordsStep ? 5 : 4;
-},
-```
-
-#### 5d. Update `currentStepProgressLabel` (lines 157-163)
-
-Replace hard-coded totals with `this.totalNumSteps`:
-```js
-currentStepProgressLabel() {
-  if (this.includeDropzoneInModal) {
-    const currentStepDisplay = this.currentStep === 0 ? 1 : this.currentStep;
-    return this.uploadYourLogoTr('stepOf', { CURRENT: currentStepDisplay, TOTAL: this.totalNumSteps });
-  }
-  return this.uploadYourLogoTr('stepOf', { CURRENT: this.currentStep - 1, TOTAL: this.totalNumSteps });
-},
-```
-
-#### 5e. Update `currentStepTrackingLabel` (lines 170-176)
-
-Make it keyword-step aware:
-```js
-currentStepTrackingLabel() {
-  const stepTwoLabel = this.currentStep === 2 && !this.canCropImage ? 'previewLogo' : 'cropLogo';
-  const steps = this.showKeywordsStep
-    ? ['logoUploader', stepTwoLabel, 'businessName', 'keywords', 'brandColors']
-    : ['logoUploader', stepTwoLabel, 'businessName', 'brandColors'];
-  return steps[this.currentStep - 1];
-},
-```
-
-#### 5f. Import LogoKeywords component
-
-Add import at top of script:
-```js
-import LogoKeywords from './LogoKeywords.vue';
-```
-
-Register in `components: { ... }`.
-
-#### 5g. Update `onSaveBusinessText` method (lines 251-255)
-
-No change needed — it already sets `currentStep = 4`. When `showKeywordsStep` is true, step 4 shows LogoKeywords. When false, step 4 shows LogoBusinessBrandColours (via `brandColoursStep` computed).
-
-#### 5h. Add `onSaveKeywords` method
-
-```js
-onSaveKeywords(payload) {
-  this.$emit('on-save-keywords', { keywords: payload.keywords });
-  this.savedKeywords = payload.keywords;
-  this.currentStep = this.brandColoursStep;
-},
-```
-
-#### 5i. Add `onGoBackFromBrandColours` method (or rename existing `onGoBackToBusinessText` usage on brand colours)
-
-```js
-onGoBackFromBrandColours() {
-  this.$emit('on-back', { currentStepTrackingLabel: this.currentStepTrackingLabel });
-  this.currentStep = this.showKeywordsStep ? 4 : 3;
-},
-```
-
-**Important**: The brand colours component currently uses `@on-go-back="onGoBackToBusinessText"` (which sets `currentStep = 3`). Change this to `@on-go-back="onGoBackFromBrandColours"` so it goes back to keywords (step 4) when the keywords step is enabled.
-
-#### 5j. Update template — add LogoKeywords between BusinessText and BrandColours
-
-Add after the LogoBusinessText block and before LogoBusinessBrandColours:
-
-```vue
-<LogoKeywords
-  v-if="showKeywordsStep && !isAttemptingToExit && currentStep === 4 && uploadedLogoData"
-  :progress-label="currentStepProgressLabel"
-  :event-category="eventCategory"
-  :saved-keywords="savedKeywords"
-  :business-name="(savedBusinessText && savedBusinessText.businessText) || ''"
-  :template-type="templateType"
-  @on-go-back="onGoBackToBusinessText"
-  @on-save="onSaveKeywords"
-/>
-```
-
-#### 5k. Update template — change BrandColours step condition
-
-Change `currentStep === 4` to `currentStep === brandColoursStep`:
-
-```vue
-<LogoBusinessBrandColours
-  v-if="!isAttemptingToExit && currentStep === brandColoursStep && uploadedLogoData && !isCurrentlySaving"
-  ...
-  @on-go-back="onGoBackFromBrandColours"
-  ...
-/>
-```
-
-#### 5l. Update `reset()` method (lines 290-299)
-
-Add:
-```js
-this.savedKeywords = null;
-```
-
-### 6. Update `UploadYourLogoApplication.vue` wrapper
-
-**File**: `src/experiences/components/UploadYourLogoApplication/UploadYourLogoApplication.vue`
-
-#### 6a. Add pass-through props (after existing props at lines 29-45)
-
-```js
-showKeywordsStep: {
-  type: Boolean,
-  required: false,
-  default: false,
-},
-templateType: {
-  type: String,
-  required: true,
-},
-```
-
-Note: `templateType` must be provided by the consumer (fallback/defaulting happens in consumer app config, not in this component).
-
-#### 6b. Pass props to `UploadYourLogoOnBoarding` in template
-
-Add to the existing `<UploadYourLogoOnBoarding>` tag:
-```vue
-:show-keywords-step="showKeywordsStep"
-:template-type="templateType"
-@on-save-keywords="onSaveKeywords"
-```
-
-#### 6c. Add event handler method
-
-```js
-onSaveKeywords(payload) {
-  this.$emit('on-save-keywords', payload);
-},
-```
-
-### 7. Add Storybook story (required)
-
-**File**: Create `src/experiences/components/UploadYourLogoOnBoarding/LogoKeywords.stories.js`
-
-Create a story following standard Storybook patterns covering:
-- Loading state (mock delayed API)
-- Populated state (mock successful response with keywords)
-- Empty state (mock failed response)
-- Pre-populated state (savedKeywords prop set)
-
-### 8. Publish package
-
-After all changes are verified (human release process; **not** a coding-agent task):
-1. Bump package version in `package.json`
-2. Run `npm run bundle-translation` to regenerate i18n bundles
-3. Perform manual validation in Storybook/integration context (no automated test runner in this repo)
-4. Publish the new version of `@designcrowd/fe-shared-lib`
-
----
-
-## Step Number Reference Table
-
-### When `showKeywordsStep = false` (default, unchanged):
-
-| currentStep | Component | Progress Display |
-|---|---|---|
-| 1 | LogoUploader | Step 0 of 4 |
-| 2 | LogoCropper/Preview | Step 1 of 4 |
-| 3 | LogoBusinessText | Step 2 of 4 |
-| 4 | LogoBusinessBrandColours | Step 3 of 4 |
-
-### When `showKeywordsStep = true`:
-
-| currentStep | Component | Progress Display |
-|---|---|---|
-| 1 | LogoUploader | Step 0 of 5 |
-| 2 | LogoCropper/Preview | Step 1 of 5 |
-| 3 | LogoBusinessText | Step 2 of 5 |
-| **4** | **LogoKeywords (NEW)** | **Step 3 of 5** |
-| 5 | LogoBusinessBrandColours | Step 4 of 5 |
-
-Note: The `useDropzone` variant adds step 0 (dropzone) and shifts totals by +1. The same logic applies — `totalNumSteps` handles this via the ternary in `data()`.
-
----
-
-## Files Changed
-
-| File | Change |
-|---|---|
-| `src/experiences/constants/api.js` | Add `KEYWORD_SUGGESTIONS_API_URL` |
-| `src/experiences/clients/brand-crowd-api.client.js` | Add `getKeywordSuggestionsAsync` method + export |
-| `src/experiences/components/UploadYourLogoOnBoarding/LogoKeywords.vue` | **New file** — keywords step component |
-| `src/experiences/components/UploadYourLogoOnBoarding/UploadYourLogoOnBoarding.vue` | New props, step routing, computed properties, methods, template |
-| `src/experiences/components/UploadYourLogoApplication/UploadYourLogoApplication.vue` | Pass-through props + event |
-| `src/experiences/components/UploadYourLogoOnBoarding/i18n/upload-your-logo.json` | Add `keywords`, `keywordsDescription` |
-| `src/experiences/components/UploadYourLogoOnBoarding/i18n/upload-your-logo.de-DE.json` | Add `keywords`, `keywordsDescription` (English placeholder) |
-| `src/experiences/components/UploadYourLogoOnBoarding/i18n/upload-your-logo.es-ES.json` | Add `keywords`, `keywordsDescription` (English placeholder) |
-| `src/experiences/components/UploadYourLogoOnBoarding/i18n/upload-your-logo.fr-CA.json` | Add `keywords`, `keywordsDescription` (English placeholder) |
-| `src/experiences/components/UploadYourLogoOnBoarding/i18n/upload-your-logo.fr-FR.json` | Add `keywords`, `keywordsDescription` (English placeholder) |
-| `src/experiences/components/UploadYourLogoOnBoarding/i18n/upload-your-logo.pt-BR.json` | Add `keywords`, `keywordsDescription` (English placeholder) |
-| `src/experiences/components/UploadYourLogoOnBoarding/i18n/upload-your-logo.pt-PT.json` | Add `keywords`, `keywordsDescription` (English placeholder) |
-| `src/experiences/components/UploadYourLogoOnBoarding/LogoKeywords.stories.js` | **New file** (required) |
+# DY-957 Phase 2: fe-shared-lib Wizard Changes
+
+## Goal
+
+Add an optional keywords step to the BYO upload wizard in `@designcrowd/fe-shared-lib`. The step fetches AI keyword suggestions, displays them in an editable textbox, and emits the keywords for the consumer to use. The step is opt-in via a `showKeywordsStep` prop (default `false`).
+
+## Repo
+
+`fe-shared-lib`
+
+## Prerequisites
+
+- Phase 1 backend endpoint deployed (needed for integration testing, not for Storybook development)
+
+## Implementation Decisions (Confirmed)
+
+- The keyword suggestions endpoint path is `/api/ai-keyword-suggestion` (this is intentionally **not** maker-prefixed).
+- `templateType` is required end-to-end; consumers must pass a non-null default value.
+- Continue action in the keywords step must be disabled while suggestions are loading.
+- Storybook coverage for `LogoKeywords` is required for this task (not optional).
+- Publishing/version bump and final validation are human-owned follow-up steps, not coding-agent scope.
+
+---
+
+## Tasks
+
+### 1. Add API constant
+
+**File**: `src/experiences/constants/api.js`
+
+Add one line to the exported object:
+
+```js
+KEYWORD_SUGGESTIONS_API_URL: '/api/ai-keyword-suggestion',
+```
+
+### 2. Add `getKeywordSuggestionsAsync` to API client
+
+**File**: `src/experiences/clients/brand-crowd-api.client.js`
+
+Add a new async method following the `searchDomainNamesByKeywordAsync` pattern (lines 71-117):
+
+```js
+const getKeywordSuggestionsAsync = async ({ businessName, templateType }) => {
+  try {
+    const url = `${API.KEYWORD_SUGGESTIONS_API_URL}?businessName=${encodeURIComponent(businessName)}&templateType=${encodeURIComponent(templateType)}`;
+    const response = await getAxios()({
+      method: 'get',
+      url,
+    });
+    return response.data;
+  } catch (error) {
+    return false;
+  }
+};
+```
+
+Behavior note: if `businessName` is empty, still call the endpoint with `businessName=` and continue normally (expected to return empty suggestions).
+
+Add `getKeywordSuggestionsAsync` to the default export object (lines 119-124).
+
+### 3. Create `LogoKeywords.vue` component
+
+**File**: Create `src/experiences/components/UploadYourLogoOnBoarding/LogoKeywords.vue`
+
+Clone the structure from `LogoBusinessText.vue` (same directory). The component should:
+
+**Props:**
+- `progressLabel` (String, required) — "Step X of Y"
+- `eventCategory` (String, required) — for analytics tracking
+- `savedKeywords` (String, optional, default: `null`) — restored keywords if user navigated back then forward
+- `businessName` (String, optional, default: `''`) — from previous step (may be empty)
+- `templateType` (String, required) — e.g. "business card"
+
+Behavior note: keep current wizard behavior where empty business name is allowed; do not block navigation if no business name is entered.
+
+**Data:**
+- `keywordsText: ''` — the editable comma-separated keywords string
+- `isLoading: false`
+
+**Mounted lifecycle:**
+```js
+async mounted() {
+  if (this.savedKeywords !== null) {
+    this.keywordsText = this.savedKeywords;
+    return;
+  }
+  this.isLoading = true;
+  try {
+    const result = await brandCrowdClient.getKeywordSuggestionsAsync({
+      businessName: this.businessName,
+      templateType: this.templateType,
+    });
+    if (result && result.keywords && result.keywords.length > 0) {
+      this.keywordsText = result.keywords.join(', ');
+    }
+  } catch {
+    // leave keywordsText as empty string
+  } finally {
+    this.isLoading = false;
+  }
+},
+```
+
+**Methods:**
+- `back()` — emits `on-go-back`
+- `save()` — no-op if `isLoading` is true; otherwise tracks event with `eventAction: 'keywords'`, `eventLabel: 'Clicked_Continue'`, then emits `on-save` with `{ keywords: this.keywordsText }`
+- `onKeywordsKeyUp(e)` — if `e.key === 'Enter'` and `!isLoading`, call `this.save()`
+
+**Template:** Mirror `LogoBusinessText.vue` layout:
+- Progress label header: `{{ progressLabel }}`
+- Heading: `{{ uploadYourLogoTr('keywords') }}`
+- Description: `{{ uploadYourLogoTr('keywordsDescription') }}`
+- Single `<input>` or `<textarea>` bound to `keywordsText`, disabled while `isLoading`, with `@keyup="onKeywordsKeyUp"`
+- Show a loading indicator (spinner or skeleton) when `isLoading` is true
+- Footer with Back button (emits `on-go-back`) and Continue button (calls `save()`)
+- Continue button must be disabled while `isLoading` is `true`
+
+**i18n:** Use the `uploadYourLogoTr` mixin (same as `LogoBusinessText.vue`).
+
+### 4. Add i18n translation keys
+
+**Files**: All 7 locale files in `src/experiences/components/UploadYourLogoOnBoarding/i18n/`
+
+Add two new keys inside the `"uploadYourLogo"` object in **every** locale file, using the **English text** in all of them:
+
+```json
+"keywords": "Keywords",
+"keywordsDescription": "Add keywords related to your business and logo"
+```
+
+Add this identical English text to:
+- `upload-your-logo.json` (English)
+- `upload-your-logo.de-DE.json`
+- `upload-your-logo.es-ES.json`
+- `upload-your-logo.fr-CA.json`
+- `upload-your-logo.fr-FR.json`
+- `upload-your-logo.pt-BR.json`
+- `upload-your-logo.pt-PT.json`
+
+**Do not translate** — a separate process will sweep the codebase and replace the English placeholders with proper translations.
+
+After editing all files, run `npm run bundle-translation` to regenerate bundled translation files.
+
+### 5. Update `UploadYourLogoOnBoarding.vue` orchestrator
+
+**File**: `src/experiences/components/UploadYourLogoOnBoarding/UploadYourLogoOnBoarding.vue`
+
+#### 5a. Add new props (after existing props at lines 115-136)
+
+```js
+showKeywordsStep: {
+  type: Boolean,
+  required: false,
+  default: false,
+},
+templateType: {
+  type: String,
+  required: true,
+},
+```
+
+Note: `templateType` must be provided by the consumer (fallback/defaulting happens in consumer app config, not in this component).
+
+#### 5b. Update `data()` (lines 142-154)
+
+Change `totalNumSteps` to be dynamic:
+```js
+totalNumSteps: this.useDropzone
+  ? (this.showKeywordsStep ? 6 : 5)
+  : (this.showKeywordsStep ? 5 : 4),
+```
+
+Add new data property:
+```js
+savedKeywords: null,
+```
+
+#### 5c. Add computed property for brand colours step number
+
+```js
+brandColoursStep() {
+  return this.showKeywordsStep ? 5 : 4;
+},
+```
+
+#### 5d. Update `currentStepProgressLabel` (lines 157-163)
+
+Replace hard-coded totals with `this.totalNumSteps`:
+```js
+currentStepProgressLabel() {
+  if (this.includeDropzoneInModal) {
+    const currentStepDisplay = this.currentStep === 0 ? 1 : this.currentStep;
+    return this.uploadYourLogoTr('stepOf', { CURRENT: currentStepDisplay, TOTAL: this.totalNumSteps });
+  }
+  return this.uploadYourLogoTr('stepOf', { CURRENT: this.currentStep - 1, TOTAL: this.totalNumSteps });
+},
+```
+
+#### 5e. Update `currentStepTrackingLabel` (lines 170-176)
+
+Make it keyword-step aware:
+```js
+currentStepTrackingLabel() {
+  const stepTwoLabel = this.currentStep === 2 && !this.canCropImage ? 'previewLogo' : 'cropLogo';
+  const steps = this.showKeywordsStep
+    ? ['logoUploader', stepTwoLabel, 'businessName', 'keywords', 'brandColors']
+    : ['logoUploader', stepTwoLabel, 'businessName', 'brandColors'];
+  return steps[this.currentStep - 1];
+},
+```
+
+#### 5f. Import LogoKeywords component
+
+Add import at top of script:
+```js
+import LogoKeywords from './LogoKeywords.vue';
+```
+
+Register in `components: { ... }`.
+
+#### 5g. Update `onSaveBusinessText` method (lines 251-255)
+
+No change needed — it already sets `currentStep = 4`. When `showKeywordsStep` is true, step 4 shows LogoKeywords. When false, step 4 shows LogoBusinessBrandColours (via `brandColoursStep` computed).
+
+#### 5h. Add `onSaveKeywords` method
+
+```js
+onSaveKeywords(payload) {
+  this.$emit('on-save-keywords', { keywords: payload.keywords });
+  this.savedKeywords = payload.keywords;
+  this.currentStep = this.brandColoursStep;
+},
+```
+
+#### 5i. Add `onGoBackFromBrandColours` method (or rename existing `onGoBackToBusinessText` usage on brand colours)
+
+```js
+onGoBackFromBrandColours() {
+  this.$emit('on-back', { currentStepTrackingLabel: this.currentStepTrackingLabel });
+  this.currentStep = this.showKeywordsStep ? 4 : 3;
+},
+```
+
+**Important**: The brand colours component currently uses `@on-go-back="onGoBackToBusinessText"` (which sets `currentStep = 3`). Change this to `@on-go-back="onGoBackFromBrandColours"` so it goes back to keywords (step 4) when the keywords step is enabled.
+
+#### 5j. Update template — add LogoKeywords between BusinessText and BrandColours
+
+Add after the LogoBusinessText block and before LogoBusinessBrandColours:
+
+```vue
+<LogoKeywords
+  v-if="showKeywordsStep && !isAttemptingToExit && currentStep === 4 && uploadedLogoData"
+  :progress-label="currentStepProgressLabel"
+  :event-category="eventCategory"
+  :saved-keywords="savedKeywords"
+  :business-name="(savedBusinessText && savedBusinessText.businessText) || ''"
+  :template-type="templateType"
+  @on-go-back="onGoBackToBusinessText"
+  @on-save="onSaveKeywords"
+/>
+```
+
+#### 5k. Update template — change BrandColours step condition
+
+Change `currentStep === 4` to `currentStep === brandColoursStep`:
+
+```vue
+<LogoBusinessBrandColours
+  v-if="!isAttemptingToExit && currentStep === brandColoursStep && uploadedLogoData && !isCurrentlySaving"
+  ...
+  @on-go-back="onGoBackFromBrandColours"
+  ...
+/>
+```
+
+#### 5l. Update `reset()` method (lines 290-299)
+
+Add:
+```js
+this.savedKeywords = null;
+```
+
+### 6. Update `UploadYourLogoApplication.vue` wrapper
+
+**File**: `src/experiences/components/UploadYourLogoApplication/UploadYourLogoApplication.vue`
+
+#### 6a. Add pass-through props (after existing props at lines 29-45)
+
+```js
+showKeywordsStep: {
+  type: Boolean,
+  required: false,
+  default: false,
+},
+templateType: {
+  type: String,
+  required: true,
+},
+```
+
+Note: `templateType` must be provided by the consumer (fallback/defaulting happens in consumer app config, not in this component).
+
+#### 6b. Pass props to `UploadYourLogoOnBoarding` in template
+
+Add to the existing `<UploadYourLogoOnBoarding>` tag:
+```vue
+:show-keywords-step="showKeywordsStep"
+:template-type="templateType"
+@on-save-keywords="onSaveKeywords"
+```
+
+#### 6c. Add event handler method
+
+```js
+onSaveKeywords(payload) {
+  this.$emit('on-save-keywords', payload);
+},
+```
+
+### 7. Add Storybook story (required)
+
+**File**: Create `src/experiences/components/UploadYourLogoOnBoarding/LogoKeywords.stories.js`
+
+Create a story following standard Storybook patterns covering:
+- Loading state (mock delayed API)
+- Populated state (mock successful response with keywords)
+- Empty state (mock failed response)
+- Pre-populated state (savedKeywords prop set)
+
+### 8. Publish package
+
+After all changes are verified (human release process; **not** a coding-agent task):
+1. Bump package version in `package.json`
+2. Run `npm run bundle-translation` to regenerate i18n bundles
+3. Perform manual validation in Storybook/integration context (no automated test runner in this repo)
+4. Publish the new version of `@designcrowd/fe-shared-lib`
+
+---
+
+## Step Number Reference Table
+
+### When `showKeywordsStep = false` (default, unchanged):
+
+| currentStep | Component | Progress Display |
+|---|---|---|
+| 1 | LogoUploader | Step 0 of 4 |
+| 2 | LogoCropper/Preview | Step 1 of 4 |
+| 3 | LogoBusinessText | Step 2 of 4 |
+| 4 | LogoBusinessBrandColours | Step 3 of 4 |
+
+### When `showKeywordsStep = true`:
+
+| currentStep | Component | Progress Display |
+|---|---|---|
+| 1 | LogoUploader | Step 0 of 5 |
+| 2 | LogoCropper/Preview | Step 1 of 5 |
+| 3 | LogoBusinessText | Step 2 of 5 |
+| **4** | **LogoKeywords (NEW)** | **Step 3 of 5** |
+| 5 | LogoBusinessBrandColours | Step 4 of 5 |
+
+Note: The `useDropzone` variant adds step 0 (dropzone) and shifts totals by +1. The same logic applies — `totalNumSteps` handles this via the ternary in `data()`.
+
+---
+
+## Files Changed
+
+| File | Change |
+|---|---|
+| `src/experiences/constants/api.js` | Add `KEYWORD_SUGGESTIONS_API_URL` |
+| `src/experiences/clients/brand-crowd-api.client.js` | Add `getKeywordSuggestionsAsync` method + export |
+| `src/experiences/components/UploadYourLogoOnBoarding/LogoKeywords.vue` | **New file** — keywords step component |
+| `src/experiences/components/UploadYourLogoOnBoarding/UploadYourLogoOnBoarding.vue` | New props, step routing, computed properties, methods, template |
+| `src/experiences/components/UploadYourLogoApplication/UploadYourLogoApplication.vue` | Pass-through props + event |
+| `src/experiences/components/UploadYourLogoOnBoarding/i18n/upload-your-logo.json` | Add `keywords`, `keywordsDescription` |
+| `src/experiences/components/UploadYourLogoOnBoarding/i18n/upload-your-logo.de-DE.json` | Add `keywords`, `keywordsDescription` (English placeholder) |
+| `src/experiences/components/UploadYourLogoOnBoarding/i18n/upload-your-logo.es-ES.json` | Add `keywords`, `keywordsDescription` (English placeholder) |
+| `src/experiences/components/UploadYourLogoOnBoarding/i18n/upload-your-logo.fr-CA.json` | Add `keywords`, `keywordsDescription` (English placeholder) |
+| `src/experiences/components/UploadYourLogoOnBoarding/i18n/upload-your-logo.fr-FR.json` | Add `keywords`, `keywordsDescription` (English placeholder) |
+| `src/experiences/components/UploadYourLogoOnBoarding/i18n/upload-your-logo.pt-BR.json` | Add `keywords`, `keywordsDescription` (English placeholder) |
+| `src/experiences/components/UploadYourLogoOnBoarding/i18n/upload-your-logo.pt-PT.json` | Add `keywords`, `keywordsDescription` (English placeholder) |
+| `src/experiences/components/UploadYourLogoOnBoarding/LogoKeywords.stories.js` | **New file** (required) |