sar/_bmad/wds/scripts/README.md

WDS Scaffold Scripts

Node.js scripts that enforce deterministic output from AI agents. Agents provide content via CLI flags; scripts produce structure.

All scripts use only Node.js stdlib (no external dependencies). Run from the project root.

---

Scripts

wds-init-scenario.js — Initialize a scenario

Creates the scenario folder and a README index file.

node src/scripts/wds-init-scenario.js \
  --scenario "01 New User Onboarding" \
  --description "New user first visit to account creation"

Output: C-UX-Scenarios/01-new-user-onboarding/README.md

---

wds-init-page.js — Initialize a page spec

Creates a new page spec file with all required sections pre-filled with placeholders.

node src/scripts/wds-init-page.js \
  --page "01 Start" \
  --scenario "01 New User Onboarding" \
  --platform "Mobile web" \
  --visibility "Public"

Output:

• C-UX-Scenarios/01-new-user-onboarding/01-start/01-start.md
• C-UX-Scenarios/01-new-user-onboarding/01-start/sketches/

After creating all pages in a scenario, run wds-nav.js to wire up navigation links.

---

wds-nav.js — Update navigation links

Scans pages in a scenario (sorted by name) and writes correct prev/next navigation rows into each page spec.

# One scenario
node src/scripts/wds-nav.js --scenario "01 New User Onboarding"

# All scenarios
node src/scripts/wds-nav.js --all

Run this after adding or removing pages, or after reordering page numbers.

---

wds-add-object.js — Append an object spec

Appends a structured object spec block to a page spec under a named section.

node src/scripts/wds-add-object.js \
  --page "C-UX-Scenarios/01-new-user-onboarding/01-start/01-start.md" \
  --section "Hero" \
  --object "Primary Headline" \
  --component "H1 heading" \
  --se "Välkommen" \
  --en "Welcome" \
  --behavior "Static display"

Object ID is auto-derived: start-hero-primary-headline

The section heading (### Section: Hero) is created if it doesn't already exist.

---

wds-add-spacing.js — Append a spacing object

Appends a spacing notation entry to the ## Spacing section of a page spec.

node src/scripts/wds-add-spacing.js \
  --page "C-UX-Scenarios/01-new-user-onboarding/01-start/01-start.md" \
  --direction v \
  --type space \
  --size xl \
  --reason "major section boundary between hero and features"

Valid directions: v (vertical), h (horizontal) Valid types: space, separator, line Valid sizes: zero, sm, md, lg, xl, 2xl, 3xl, flex

Spacing ID is auto-derived: start-v-space-xl

---

wds-validate.js — Validate page specs

Checks page spec files for structural correctness.

# Single page
node src/scripts/wds-validate.js \
  --page "C-UX-Scenarios/01-new-user-onboarding/01-start/01-start.md"

# All pages in a scenario
node src/scripts/wds-validate.js --scenario "01 New User Onboarding"

# All scenarios
node src/scripts/wds-validate.js --all

Validates:

• Required sections present
• Object IDs are kebab-case with correct page prefix
• No duplicate Object IDs
• Navigation rows (3 expected)
• Metadata table has all required properties
• Sketches folder exists
• SE + EN content present for each object

---

How agents use these scripts

1. Agent calls wds-init-scenario.js with scenario name and description
2. Agent calls wds-init-page.js for each page in the scenario
3. Agent calls wds-nav.js to wire navigation after all pages exist
4. Agent calls wds-add-object.js for each UI object, providing Swedish and English content
5. Agent calls wds-add-spacing.js for each spacing decision
6. Agent calls wds-validate.js to confirm the spec is structurally correct before handoff

The agent never writes raw markdown — it only supplies content as flag values. The scripts own all structural decisions.

---

File location convention

C-UX-Scenarios/
  {scenario-slug}/
    README.md
    {page-slug}/
      {page-slug}.md
      sketches/
        {page-slug}-concept.jpg

Example: C-UX-Scenarios/01-new-user-onboarding/02-signup/02-signup.md