156 lines
4.0 KiB
Markdown
156 lines
4.0 KiB
Markdown
|
# 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.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 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.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 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`
|