chore: initial monorepo scaffold + WDS Phase 1+2 artifacts
- Nx 22.7 monorepo (pnpm 11.1, TypeScript 5.9, Node 24) - apps/api: NestJS 11 (CJS conforme CODING-RULES.md PGD-DB-004) - apps/web: React 19 + Vite 8 (ESM) - libs/shared/api-interface: Zod contract base - Docker Compose dev: Postgres 18, Valkey 8, MinIO, Mailpit - WDS artifacts: - design-artifacts/A-Product-Brief/ (5 docs canônicos + 16 dialogs) - design-artifacts/B-Trigger-Map/ (hub + 4 personas + feature impact) - Stack canon: STACK.md v2.2 + CODING-RULES.md v2.0 + brand.md - AGENTS.md + README.md como entrada para devs/agentes Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
155
_bmad/wds/scripts/README.md
Normal file
155
_bmad/wds/scripts/README.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user