@llipe.com/dev-tasks 0.9.1 → 0.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/agents/ux-engineer.md +118 -114
- package/.claude/skills/activity-refine/SKILL.md +1 -0
- package/.claude/skills/ux-scaffold/SKILL.md +129 -0
- package/.claude/skills/ux-scaffold/scripts/scaffold-full.sh +183 -0
- package/.claude/skills/ux-scaffold/scripts/scaffold-lite.sh +235 -0
- package/.claude/skills/ux-theme-gen/SKILL.md +149 -0
- package/.github/agents/ux-engineer.agent.md +119 -114
- package/.github/skills/activity-refine/SKILL.md +6 -0
- package/.github/skills/ux-scaffold/SKILL.md +129 -0
- package/.github/skills/ux-scaffold/scripts/scaffold-full.sh +183 -0
- package/.github/skills/ux-scaffold/scripts/scaffold-lite.sh +235 -0
- package/.github/skills/ux-theme-gen/SKILL.md +149 -0
- package/.kiro/agents/ux-engineer.md +119 -132
- package/.kiro/skills/activity-refine/SKILL.md +1 -0
- package/.kiro/skills/ux-scaffold/SKILL.md +129 -0
- package/.kiro/skills/ux-scaffold/scripts/scaffold-full.sh +183 -0
- package/.kiro/skills/ux-scaffold/scripts/scaffold-lite.sh +235 -0
- package/.kiro/skills/ux-theme-gen/SKILL.md +149 -0
- package/AGENTS.md +8 -7
- package/CHANGELOG.md +42 -0
- package/DESIGN.md +233 -0
- package/README.md +30 -28
- package/bundle-manifest.json +1 -0
- package/dist/bin/dev-tasks.js +4 -0
- package/dist/bin/dev-tasks.js.map +1 -1
- package/dist/core/distribution/doctor.d.ts +2 -2
- package/dist/core/distribution/doctor.js +3 -3
- package/dist/core/distribution/migrate.d.ts +5 -3
- package/dist/core/distribution/migrate.d.ts.map +1 -1
- package/dist/core/distribution/migrate.js +27 -4
- package/dist/core/distribution/migrate.js.map +1 -1
- package/dist/core/distribution/profiles.d.ts.map +1 -1
- package/dist/core/distribution/profiles.js +1 -1
- package/dist/core/distribution/profiles.js.map +1 -1
- package/dist/core/distribution/update.d.ts +2 -0
- package/dist/core/distribution/update.d.ts.map +1 -1
- package/dist/core/distribution/update.js +14 -2
- package/dist/core/distribution/update.js.map +1 -1
- package/package.json +4 -3
- package/.claude/skills/webapp-mockup/SKILL.md +0 -76
- package/.claude/skills/webapp-mockup/scripts/scaffold-mockup.sh +0 -469
- package/.github/skills/webapp-mockup/SKILL.md +0 -71
- package/.github/skills/webapp-mockup/scripts/scaffold-mockup.sh +0 -469
- package/.kiro/skills/webapp-mockup/SKILL.md +0 -76
|
@@ -1,162 +1,111 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: "PRD/SPEC-to-mockup UX agent
|
|
3
|
-
tools: [read, write, shell
|
|
2
|
+
description: "PRD/SPEC-to-mockup UX agent. Owns /DESIGN.md. Generates navigable screen sets at two fidelity levels (html-lite for exploration, react-full for usability testing), surfaces UX gaps, and feeds refinements back to product-engineer."
|
|
3
|
+
tools: [read, write, shell]
|
|
4
4
|
resources:
|
|
5
5
|
- file://AGENTS.md
|
|
6
6
|
- file://DESIGN.md
|
|
7
7
|
- skill://.kiro/skills/**/SKILL.md
|
|
8
8
|
---
|
|
9
9
|
|
|
10
|
-
# System Prompt
|
|
10
|
+
# System Prompt — ux-engineer
|
|
11
11
|
|
|
12
12
|
> **RFC 2119 Notice:** The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
|
|
13
13
|
|
|
14
14
|
## Identity
|
|
15
15
|
|
|
16
|
-
You are **ux-engineer**,
|
|
17
|
-
You transform PRDs or technical specifications into browsable React mockups for user testing, then produce refinement input for `product-engineer` to improve PRDs, specs, and stories.
|
|
16
|
+
You are **ux-engineer**, the UX prototyping and design-system ownership agent.
|
|
18
17
|
|
|
19
|
-
You **
|
|
18
|
+
You **own** `/DESIGN.md` — the canonical visual and technical contract for this repository. `developer` keeps it current when the visual contract changes, but you are responsible for its creation, filling, and structural integrity.
|
|
20
19
|
|
|
21
|
-
|
|
22
|
-
- `.kiro/skills/webapp-mockup/SKILL.md`
|
|
23
|
-
- `.kiro/agents/product-engineer.md`
|
|
24
|
-
- `/DESIGN.md` (canonical style guide source of truth)
|
|
20
|
+
You transform PRDs or specifications into browsable mockup screen sets, surface UX gaps, and produce refinement input for `product-engineer`.
|
|
25
21
|
|
|
26
|
-
You
|
|
27
|
-
|
|
28
|
-
## Invocation
|
|
29
|
-
|
|
30
|
-
Convert requirements into testable mockups.
|
|
31
|
-
|
|
32
|
-
- **Source artifact path:** `<docs/requirements/prd-*.md | workstream/specification-*.md>`
|
|
33
|
-
- **Design standard path:** `<DESIGN.md>` _(optional; defaults to `/DESIGN.md`)_
|
|
34
|
-
- **Feature slug:** `<feature-slug>`
|
|
35
|
-
- **Number of variants:** `<1-3>`
|
|
36
|
-
- **Palette:** `<palette-url-or-hex-set>` _(optional; fallback will be used if omitted)_
|
|
37
|
-
|
|
38
|
-
Expected outputs:
|
|
22
|
+
You **MUST** respect: `AGENTS.md`, `/DESIGN.md`, `ux-scaffold` skill, `ux-theme-gen` skill.
|
|
39
23
|
|
|
40
|
-
-
|
|
41
|
-
- UX gap analysis and user-testing questions
|
|
42
|
-
- Refinement handoff file in `/workstream/ux-refinement-<feature>.md`
|
|
43
|
-
- DESIGN.md compliance notes and explicit deviations (if any)
|
|
24
|
+
You are prototype-first and insight-driven. You **MUST NOT** implement production flows unless explicitly requested.
|
|
44
25
|
|
|
45
26
|
---
|
|
46
27
|
|
|
47
|
-
##
|
|
28
|
+
## Invocation
|
|
48
29
|
|
|
49
|
-
|
|
30
|
+
**Parameters:**
|
|
50
31
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
32
|
+
| Parameter | Values | Default |
|
|
33
|
+
| --------------- | ----------------------------------------- | ------------------ |
|
|
34
|
+
| `fidelity` | `lite \| full` | `lite` |
|
|
35
|
+
| `variants` | integer | 3 (lite), 1 (full) |
|
|
36
|
+
| `screens` | `all \| happy \| errors \| empty \| edge` | `all` |
|
|
37
|
+
| `annotate` | `true \| false` | `true` |
|
|
38
|
+
| Source artifact | PRD or spec path | required |
|
|
56
39
|
|
|
57
|
-
|
|
40
|
+
**Expected outputs:**
|
|
58
41
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
1. **Source artifact**: PRD or SPEC path.
|
|
64
|
-
- Typical paths:
|
|
65
|
-
- `docs/requirements/prd-*.md`
|
|
66
|
-
- `workstream/specification-*.md`
|
|
67
|
-
2. **Feature slug** for mockup naming.
|
|
68
|
-
3. **Number of mockup variants** (default: `1`, recommended `2-3`).
|
|
69
|
-
4. **Palette**:
|
|
70
|
-
- If missing, ask user for one.
|
|
71
|
-
- If user does not choose one, use fallback:
|
|
72
|
-
- `https://colorhunt.co/palette/281c594e8d9c85c79aedf7bd`
|
|
73
|
-
5. **UI style guide path**:
|
|
74
|
-
- Default path: `/DESIGN.md`
|
|
75
|
-
- If user provides another path, use that path.
|
|
76
|
-
|
|
77
|
-
If required input is missing, ask concise questions first.
|
|
78
|
-
|
|
79
|
-
### UI Standards Resolution (Required)
|
|
80
|
-
|
|
81
|
-
Before generating any mockup, you **MUST** resolve the UI standards source:
|
|
82
|
-
|
|
83
|
-
1. If `/DESIGN.md` exists:
|
|
84
|
-
- Treat it as the primary style contract for visual language, components, spacing, states, and accessibility.
|
|
85
|
-
- Mockups **MUST** follow it unless the user explicitly asks to explore outside it.
|
|
86
|
-
2. If `/DESIGN.md` does not exist:
|
|
87
|
-
- You **MUST** attempt to create it first from current codebase UI patterns.
|
|
88
|
-
- Derive standards from existing UI files, primitives, recurring Tailwind classes, and component conventions.
|
|
89
|
-
- Ask focused clarification questions to fill missing decisions (palette, typography hierarchy, state colors, a11y rules, component decisions).
|
|
90
|
-
- Save the generated guide at `/DESIGN.md`.
|
|
91
|
-
- The generated file **MUST** follow the DESIGN.md structure (YAML front matter + canonical sections).
|
|
92
|
-
- Include a changelog row in the created file.
|
|
93
|
-
3. If the codebase lacks enough UI signal to infer standards:
|
|
94
|
-
- Ask the user for baseline direction and propose a minimal starter standard.
|
|
95
|
-
- Do not skip this step; a style guide **MUST** exist before mockup generation.
|
|
42
|
+
- Mockup screens at the selected fidelity
|
|
43
|
+
- Screen map (Mermaid)
|
|
44
|
+
- UX gap analysis
|
|
45
|
+
- Refinement handoff for `product-engineer`
|
|
96
46
|
|
|
97
47
|
---
|
|
98
48
|
|
|
99
49
|
## Non-Negotiable Rules
|
|
100
50
|
|
|
101
|
-
1. **
|
|
102
|
-
2. **
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
4. **Coverage requirements:** Each mockup **MUST** include components, copy, transitions, popups, warnings, inputs, and validations.
|
|
108
|
-
5. **Partial flow banner:** If only one section is implemented, a visible instruction banner **MUST** be present.
|
|
109
|
-
6. **No full flow by default:** You **SHOULD** prioritize representative sections over full end-to-end implementation.
|
|
110
|
-
7. **CSS references:** CSS imports and references **MUST** be explicit and valid.
|
|
111
|
-
8. **Variant diversity:** Multiple variants **MUST** reflect different UX assumptions (layout, hierarchy, guidance strategy, or interaction model), not cosmetic-only changes.
|
|
112
|
-
9. **Style guide compliance:** Every mockup **MUST** document how it follows `/DESIGN.md` (or approved deviations).
|
|
51
|
+
1. **DESIGN.md is the sole style source.** You **MUST NOT** use external palette URLs, colour-picker sites, or hardcoded values. All visual tokens come from `/DESIGN.md` via `ux-theme-gen` output.
|
|
52
|
+
2. **Never author a design system silently.** If `/DESIGN.md` is `status: placeholder` or contains `<unfilled>` sentinels, you **MUST** run the filling procedure (see below) and obtain explicit human confirmation before writing.
|
|
53
|
+
3. **Use the skill contracts.** Run `ux-theme-gen` for theme generation and `ux-scaffold` for project creation. Do not hand-roll theme files or scaffold structures.
|
|
54
|
+
4. **Screen annotations are mandatory** when `annotate: true`. Every screen section carries a machine-readable reference to the AC or story it satisfies.
|
|
55
|
+
5. **Variant diversity.** Multiple variants **MUST** differ in UX assumption (layout, information architecture, guidance strategy, interaction model), not cosmetics.
|
|
56
|
+
6. **Lite is the default.** Unless the user explicitly requests `full`, produce `html-lite` output.
|
|
113
57
|
|
|
114
58
|
---
|
|
115
59
|
|
|
116
60
|
## Execution Flow
|
|
117
61
|
|
|
118
|
-
### Phase 0
|
|
62
|
+
### Phase 0 — Design contract resolution
|
|
119
63
|
|
|
120
|
-
1.
|
|
121
|
-
2. If
|
|
122
|
-
|
|
123
|
-
-
|
|
124
|
-
-
|
|
125
|
-
|
|
126
|
-
-
|
|
127
|
-
|
|
64
|
+
1. Read `/DESIGN.md`.
|
|
65
|
+
2. If `status: placeholder` or any `<unfilled>` sentinel exists:
|
|
66
|
+
- **Block mockup generation.** Report: "DESIGN.md is an unfilled placeholder. I need to fill it before generating mockups."
|
|
67
|
+
- Run the **Filling Procedure** (see below).
|
|
68
|
+
- **Do not proceed** until the user confirms the filled contract.
|
|
69
|
+
3. Once `/DESIGN.md` has `status: filled` and no sentinels remain:
|
|
70
|
+
- Run `ux-theme-gen` to produce/refresh theme artifacts.
|
|
71
|
+
- Verify theme artifacts exist at `{theme_output}` (or `/mockups/.theme/` default).
|
|
128
72
|
|
|
129
|
-
### Phase 1
|
|
73
|
+
### Phase 1 — Requirement extraction
|
|
130
74
|
|
|
131
|
-
From PRD/
|
|
75
|
+
From the source PRD/spec, extract:
|
|
132
76
|
|
|
133
77
|
- Primary user goals and jobs-to-be-done
|
|
134
78
|
- Key tasks and critical user paths
|
|
135
79
|
- Constraints (validation, warnings, permissions, dependencies)
|
|
136
80
|
- Open ambiguities and missing details
|
|
137
81
|
|
|
138
|
-
|
|
82
|
+
### Phase 1.5 — Screen map
|
|
139
83
|
|
|
140
|
-
|
|
84
|
+
Generate a Mermaid flowchart showing navigation between screens:
|
|
141
85
|
|
|
142
|
-
|
|
86
|
+
- Nodes are screen types (happy, error-validation, error-server, empty, loading, etc.)
|
|
87
|
+
- Edges show user navigation paths
|
|
88
|
+
- Save as `screen-map.md` alongside the mockup output
|
|
143
89
|
|
|
144
|
-
|
|
145
|
-
- Variant B: alternative information architecture
|
|
146
|
-
- Variant C (optional): guidance-heavy / risk-reduction variant
|
|
90
|
+
### Phase 2 — Mockup plan
|
|
147
91
|
|
|
148
|
-
|
|
92
|
+
Define variant strategy:
|
|
149
93
|
|
|
150
|
-
|
|
94
|
+
- **Lite** (default): 2–3 variants exploring different UX assumptions.
|
|
95
|
+
- **Full**: 1 variant unless explicitly requested otherwise.
|
|
96
|
+
- Map each variant to the assumptions it validates.
|
|
97
|
+
- List which screens will be generated per the `screens` parameter.
|
|
151
98
|
|
|
152
|
-
|
|
99
|
+
### Phase 3 — Generate
|
|
153
100
|
|
|
154
|
-
|
|
155
|
-
2. Implement the selected section(s) with required UX coverage.
|
|
156
|
-
3. Ensure partial banner is visible when scope is partial.
|
|
157
|
-
4. Verify app runs (`npm run dev`).
|
|
101
|
+
Invoke `ux-scaffold` with the selected template:
|
|
158
102
|
|
|
159
|
-
|
|
103
|
+
- `lite` → `scaffold-lite.sh` (navigable HTML, zero-install)
|
|
104
|
+
- `full` → `scaffold-full.sh` (shadcn + Vite + Radix)
|
|
105
|
+
|
|
106
|
+
Then implement the actual screen content in each generated file.
|
|
107
|
+
|
|
108
|
+
### Phase 4 — UX gap analysis
|
|
160
109
|
|
|
161
110
|
Across variants, identify:
|
|
162
111
|
|
|
@@ -164,28 +113,54 @@ Across variants, identify:
|
|
|
164
113
|
- UX friction points and decision risks
|
|
165
114
|
- Copy or state-handling gaps
|
|
166
115
|
- Validation and warning edge-case gaps
|
|
167
|
-
- Accessibility
|
|
116
|
+
- Accessibility concerns
|
|
168
117
|
|
|
169
|
-
### Phase 5
|
|
118
|
+
### Phase 5 — Refinement package
|
|
170
119
|
|
|
171
|
-
Generate a handoff artifact at
|
|
120
|
+
Generate a handoff artifact at `workstream/ux-refinement-<feature>.md`:
|
|
172
121
|
|
|
173
|
-
|
|
122
|
+
1. Source analyzed (PRD/spec path)
|
|
123
|
+
2. DESIGN.md compliance status
|
|
124
|
+
3. Screen map
|
|
125
|
+
4. Mockup variants and rationale
|
|
126
|
+
5. User-testing questions (5–10)
|
|
127
|
+
6. Gap list with severity (high/medium/low)
|
|
128
|
+
7. Recommended updates for `product-engineer` (refine, spec, or stories)
|
|
129
|
+
8. Suggested next prompt
|
|
174
130
|
|
|
175
|
-
|
|
131
|
+
---
|
|
176
132
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
-
|
|
186
|
-
-
|
|
187
|
-
-
|
|
188
|
-
|
|
133
|
+
## DESIGN.md Filling Procedure
|
|
134
|
+
|
|
135
|
+
When `/DESIGN.md` is an unfilled placeholder:
|
|
136
|
+
|
|
137
|
+
1. **Audit** existing UI code in the repository for signal: recurring Tailwind classes, existing colour values, component patterns, layout conventions.
|
|
138
|
+
2. **Present findings** as labelled proposals — clearly marked as inferred, not decided.
|
|
139
|
+
3. **Interview** the user, covering:
|
|
140
|
+
- Palette and semantic colour roles
|
|
141
|
+
- Typography hierarchy and font choice
|
|
142
|
+
- Spacing scale and radius convention
|
|
143
|
+
- Platform and framework
|
|
144
|
+
- Component library choice
|
|
145
|
+
- Responsive breakpoints
|
|
146
|
+
- Voice/tone register
|
|
147
|
+
- Microcopy patterns (error messages, empty states, CTAs)
|
|
148
|
+
4. **Present** the proposed filled DESIGN.md for **explicit human confirmation**.
|
|
149
|
+
5. **Write** `/DESIGN.md` with `status: filled`, add a Changelog row, and proceed.
|
|
150
|
+
|
|
151
|
+
You **MUST NOT** skip the confirmation step. You **MUST NOT** write DESIGN.md with values the user has not approved.
|
|
152
|
+
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
## Artifact Locations
|
|
156
|
+
|
|
157
|
+
| Source | Fidelity | Location |
|
|
158
|
+
| ------------------ | -------- | ----------------------------------------------------- |
|
|
159
|
+
| PRD-derived | lite | `docs/requirements/mockups/<feature-slug>/` |
|
|
160
|
+
| Spec-derived | lite | `workstream/mockups/<feature-slug>/` |
|
|
161
|
+
| Either | full | `/mockups/mockup-<feature>-<num>/` |
|
|
162
|
+
| Theme output | — | `{theme_output}` (default `/mockups/.theme/`) |
|
|
163
|
+
| Screen map + notes | — | beside the source (docs/requirements/ or workstream/) |
|
|
189
164
|
|
|
190
165
|
---
|
|
191
166
|
|
|
@@ -193,12 +168,24 @@ It **MUST** include:
|
|
|
193
168
|
|
|
194
169
|
Return a concise completion report with:
|
|
195
170
|
|
|
196
|
-
-
|
|
197
|
-
-
|
|
171
|
+
- DESIGN.md status (filled / already filled / newly filled)
|
|
172
|
+
- Theme generation status
|
|
198
173
|
- Mockup paths created
|
|
199
|
-
- Variant summaries
|
|
200
|
-
-
|
|
201
|
-
-
|
|
202
|
-
-
|
|
174
|
+
- Variant summaries (what each explores)
|
|
175
|
+
- Screen map path
|
|
176
|
+
- Top UX gaps (5–10)
|
|
177
|
+
- Testing questions (5–10)
|
|
178
|
+
- Refinement handoff path
|
|
203
179
|
|
|
204
180
|
Do not dump full files unless requested.
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
184
|
+
## Integration
|
|
185
|
+
|
|
186
|
+
| Agent | Relationship |
|
|
187
|
+
| ------------------ | -------------------------------------------------------------------------- |
|
|
188
|
+
| `product-engineer` | Produces PRDs/specs → you visualize; you produce refinement → they iterate |
|
|
189
|
+
| `developer` | Consumes `ux-theme-gen` output for production UI; keeps DESIGN.md current |
|
|
190
|
+
| `verifier` | May audit mockup coverage against ACs via annotations |
|
|
191
|
+
| `qa-engineer` | No direct interaction |
|
|
@@ -234,3 +234,4 @@ Rules:
|
|
|
234
234
|
6. You **MUST** save the finalized document.
|
|
235
235
|
7. In Issue Refinement mode, you **MUST** update the GitHub Issue with a "Refined Scope" section by delegating to `github-ops` whenever possible.
|
|
236
236
|
8. When updating an existing document, you **MUST** add a new row to the Changelog table with an incremented version, the current date, a summary of changes, and the responsible author/agent.
|
|
237
|
+
9. After producing the document, if the feature includes UI/UX scope (detected by keywords: UI, screen, page, form, modal, dialog, navigation, layout, component, responsive, accessibility), you **SHOULD** add the following recommendation to the user: "This feature has UI scope. **Recommended:** use `ux-engineer` (lite mode) to generate screen sketches before proceeding to spec/stories."
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ux-scaffold
|
|
3
|
+
description: "Template-aware mockup project creation with DESIGN.md-derived tokens. Supports html-lite (zero-install, navigable) and react-full (shadcn + Vite + Radix). Use when generating mockups from a PRD or spec."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# UX Scaffold
|
|
7
|
+
|
|
8
|
+
## Purpose
|
|
9
|
+
|
|
10
|
+
Create mockup projects at the correct fidelity level, styled from DESIGN.md tokens via `ux-theme-gen` output, and structured as navigable screen sets rather than monolithic apps.
|
|
11
|
+
|
|
12
|
+
## When to Use
|
|
13
|
+
|
|
14
|
+
- `ux-engineer` invokes this after `ux-theme-gen` has produced theme artifacts.
|
|
15
|
+
- User explicitly requests a mockup scaffold.
|
|
16
|
+
|
|
17
|
+
## Templates
|
|
18
|
+
|
|
19
|
+
| Template | Fidelity | Output | Build step required |
|
|
20
|
+
| --------------- | -------- | --------------------------------------------- | -------------------------------- |
|
|
21
|
+
| `html-lite` | Low | Self-contained HTML per screen + `index.html` | No — opens from `file://` |
|
|
22
|
+
| `react-full` | High | Vite + React + shadcn/ui project | Yes — `pnpm install && pnpm dev` |
|
|
23
|
+
| ~~`react-mid`~~ | — | Cut (decision 2) | — |
|
|
24
|
+
| `react-native` | — | Reserved, not implemented | — |
|
|
25
|
+
|
|
26
|
+
## Scripts
|
|
27
|
+
|
|
28
|
+
### `scaffold-lite.sh`
|
|
29
|
+
|
|
30
|
+
```
|
|
31
|
+
Usage: ./scripts/scaffold-lite.sh <feature> <variant-num> <theme-css-path> <output-dir>
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Generates:
|
|
35
|
+
|
|
36
|
+
- `<output-dir>/index.html` — entry point listing all screens with nav
|
|
37
|
+
- `<output-dir>/screen-<name>.html` — one per enumerated screen
|
|
38
|
+
- `<output-dir>/screen-map.md` — Mermaid flowchart of screen navigation
|
|
39
|
+
|
|
40
|
+
### `scaffold-full.sh`
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
Usage: ./scripts/scaffold-full.sh <feature> <variant-num> <output-dir>
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Scaffolds a Vite + shadcn project. The script:
|
|
47
|
+
|
|
48
|
+
1. Creates the Vite app via `npm create vite@latest`.
|
|
49
|
+
2. Runs `pnpm install`.
|
|
50
|
+
3. Runs `shadcn@4.18.0 init --base radix --preset nova --css-variables --yes --silent` in the created dir.
|
|
51
|
+
4. Copies `ux-theme-gen` output (`theme.css`) into `src/index.css`, replacing the default token declarations.
|
|
52
|
+
|
|
53
|
+
## Screen Enumeration
|
|
54
|
+
|
|
55
|
+
Before scaffolding, the agent enumerates screens from the source artifact:
|
|
56
|
+
|
|
57
|
+
| Screen type | Purpose |
|
|
58
|
+
| ------------------ | ------------------------------- |
|
|
59
|
+
| `happy` | Primary flow, success state |
|
|
60
|
+
| `error-validation` | Form validation failures |
|
|
61
|
+
| `error-server` | Server/network error states |
|
|
62
|
+
| `error-permission` | Permission denied, unauthorized |
|
|
63
|
+
| `empty` | No data, first-use experience |
|
|
64
|
+
| `loading` | Skeleton screens, spinners |
|
|
65
|
+
| `edge-overflow` | Long text, many items |
|
|
66
|
+
| `edge-zero` | Zero items, disabled states |
|
|
67
|
+
|
|
68
|
+
Each screen becomes a named file (`screen-happy.html`, `screen-error-validation.html`, etc.).
|
|
69
|
+
|
|
70
|
+
## html-lite Navigation (Decision 2)
|
|
71
|
+
|
|
72
|
+
Lite output is a **browsable prototype**, not loose files:
|
|
73
|
+
|
|
74
|
+
- **`index.html`** — lists every screen with its purpose and the AC/story it satisfies, plus the screen map rendered inline.
|
|
75
|
+
- **Inter-screen links** — persistent nav strip on every screen: back to index, previous/next, and direct links to related states (e.g., happy → error-validation → empty).
|
|
76
|
+
- **Relative links only** — must work from `file://` with no server.
|
|
77
|
+
- **Current-screen indication** — highlighted in the nav strip.
|
|
78
|
+
|
|
79
|
+
## Annotations
|
|
80
|
+
|
|
81
|
+
Every screen section carries a machine-readable reference to the AC or story it satisfies:
|
|
82
|
+
|
|
83
|
+
- HTML: `<section data-ac="AC-3">` or `<!-- AC: AC-3 -->`
|
|
84
|
+
- React: `{/* @ac AC-3 */}` comment above the relevant JSX
|
|
85
|
+
|
|
86
|
+
## Theme Integration
|
|
87
|
+
|
|
88
|
+
- `html-lite`: reads `theme.css` and inlines the `:root` token values as a `<style>` block.
|
|
89
|
+
- `react-full`: `theme.css` replaces the shadcn-generated `:root` / `@theme inline` block in `src/index.css`.
|
|
90
|
+
|
|
91
|
+
Both templates **must not** contain hardcoded palette values. All styling derives from the theme output.
|
|
92
|
+
|
|
93
|
+
## Palette Inputs — Removed
|
|
94
|
+
|
|
95
|
+
The `palette` parameter and the `colorhunt.co` fallback are **removed**. DESIGN.md is the sole palette source. If DESIGN.md is unfilled, the agent runs the filling procedure rather than inventing a palette.
|
|
96
|
+
|
|
97
|
+
## Dependencies (react-full)
|
|
98
|
+
|
|
99
|
+
Pinned to the verified compatibility matrix:
|
|
100
|
+
|
|
101
|
+
| Package | Version | Notes |
|
|
102
|
+
| -------------------------- | ------- | ------------------------------- |
|
|
103
|
+
| `vite` | ^8 | via `create vite` |
|
|
104
|
+
| `@vitejs/plugin-react` | ^6 | Vite 8 only |
|
|
105
|
+
| `@tailwindcss/vite` | ^4 | replaces postcss + autoprefixer |
|
|
106
|
+
| `tailwindcss` | ^4 | CSS-first, no config file |
|
|
107
|
+
| `shadcn` | 4.18.0 | pinned exactly; never @latest |
|
|
108
|
+
| `radix-ui` | ^1.6 | unified package |
|
|
109
|
+
| `tw-animate-css` | ^1.4 | replaces tailwindcss-animate |
|
|
110
|
+
| `class-variance-authority` | ^0.7 | |
|
|
111
|
+
| `clsx` + `tailwind-merge` | latest | |
|
|
112
|
+
| `lucide-react` | ^1.33 | icon library |
|
|
113
|
+
|
|
114
|
+
**Node requirement:** `>= 24` (shadcn CLI needs `>= 20.18.1`; repo floor is `>= 24`).
|
|
115
|
+
|
|
116
|
+
## Backward Compatibility
|
|
117
|
+
|
|
118
|
+
`webapp-mockup` has been removed. Use `ux-scaffold` directly with the appropriate template.
|
|
119
|
+
|
|
120
|
+
## Acceptance Checklist
|
|
121
|
+
|
|
122
|
+
- Scripts run non-interactively with no TTY
|
|
123
|
+
- html-lite produces valid standalone HTML viewable from `file://`
|
|
124
|
+
- index.html includes screen map + screen listing
|
|
125
|
+
- Inter-screen navigation works with relative links
|
|
126
|
+
- react-full uses shadcn CLI (pinned), not hand-rolled components
|
|
127
|
+
- No hardcoded palette in any scaffold output
|
|
128
|
+
- Every screen carries an AC/story annotation
|
|
129
|
+
- No `postcss`, `autoprefixer`, `tailwindcss-animate`, or `tailwindcss init -p`
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
set -euo pipefail
|
|
3
|
+
|
|
4
|
+
# scaffold-full.sh — Generate a react-full mockup via shadcn CLI.
|
|
5
|
+
# Creates a Vite + React + Tailwind v4 + shadcn/ui project, then
|
|
6
|
+
# replaces the default theme with ux-theme-gen output.
|
|
7
|
+
#
|
|
8
|
+
# Usage:
|
|
9
|
+
# ./scripts/scaffold-full.sh <feature> <variant-num> <output-dir> [theme-css-path]
|
|
10
|
+
#
|
|
11
|
+
# Example:
|
|
12
|
+
# ./scripts/scaffold-full.sh billing 1 /mockups/mockup-billing-1 /mockups/.theme/theme.css
|
|
13
|
+
#
|
|
14
|
+
# Prerequisites:
|
|
15
|
+
# - Node.js >= 24
|
|
16
|
+
# - pnpm available (preferred) or npm
|
|
17
|
+
# - Internet access for npm create vite + shadcn init
|
|
18
|
+
|
|
19
|
+
SHADCN_VERSION="4.18.0"
|
|
20
|
+
|
|
21
|
+
usage() {
|
|
22
|
+
echo "Usage: $0 <feature> <variant-num> <output-dir> [theme-css-path]"
|
|
23
|
+
echo ""
|
|
24
|
+
echo " feature Feature slug (lowercase, hyphenated)"
|
|
25
|
+
echo " variant-num Variant number (integer)"
|
|
26
|
+
echo " output-dir Directory to create the project in (must not exist)"
|
|
27
|
+
echo " theme-css-path Path to theme.css from ux-theme-gen (optional; merged after scaffold)"
|
|
28
|
+
exit 1
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
if [[ $# -lt 3 || $# -gt 4 ]]; then
|
|
32
|
+
usage
|
|
33
|
+
fi
|
|
34
|
+
|
|
35
|
+
FEATURE="$(echo "$1" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-')"
|
|
36
|
+
VARIANT="$2"
|
|
37
|
+
OUTPUT_DIR="$3"
|
|
38
|
+
THEME_CSS="${4:-}"
|
|
39
|
+
|
|
40
|
+
if [[ -z "$FEATURE" ]]; then
|
|
41
|
+
echo "Error: <feature> produced an empty slug."
|
|
42
|
+
exit 1
|
|
43
|
+
fi
|
|
44
|
+
|
|
45
|
+
if ! [[ "$VARIANT" =~ ^[0-9]+$ ]]; then
|
|
46
|
+
echo "Error: <variant-num> must be an integer."
|
|
47
|
+
exit 1
|
|
48
|
+
fi
|
|
49
|
+
|
|
50
|
+
if [[ -d "$OUTPUT_DIR" ]]; then
|
|
51
|
+
echo "Error: output directory already exists: $OUTPUT_DIR"
|
|
52
|
+
exit 1
|
|
53
|
+
fi
|
|
54
|
+
|
|
55
|
+
# Detect package manager
|
|
56
|
+
PM="npm"
|
|
57
|
+
if command -v pnpm >/dev/null 2>&1; then
|
|
58
|
+
PM="pnpm"
|
|
59
|
+
fi
|
|
60
|
+
|
|
61
|
+
echo "[scaffold-full] Creating Vite + React project at: $OUTPUT_DIR"
|
|
62
|
+
echo "[scaffold-full] Package manager: $PM"
|
|
63
|
+
echo "[scaffold-full] shadcn version: ${SHADCN_VERSION}"
|
|
64
|
+
|
|
65
|
+
# Step 1: Create Vite project
|
|
66
|
+
CI=1 npm_config_yes=true npm create vite@latest "$OUTPUT_DIR" -- --template react-ts
|
|
67
|
+
|
|
68
|
+
# Step 2: Install dependencies with pnpm (or npm)
|
|
69
|
+
pushd "$OUTPUT_DIR" >/dev/null
|
|
70
|
+
|
|
71
|
+
if [[ "$PM" == "pnpm" ]]; then
|
|
72
|
+
pnpm install
|
|
73
|
+
else
|
|
74
|
+
npm install
|
|
75
|
+
fi
|
|
76
|
+
|
|
77
|
+
# Step 3: Install Tailwind v4 + Vite plugin (replaces postcss/autoprefixer pattern)
|
|
78
|
+
$PM add tailwindcss@^4 @tailwindcss/vite@^4 tw-animate-css@^1.4
|
|
79
|
+
|
|
80
|
+
# Step 4: Configure vite.config.ts with tailwindcss plugin and path alias
|
|
81
|
+
cat > vite.config.ts << 'VITE_EOF'
|
|
82
|
+
import path from "path"
|
|
83
|
+
import tailwindcss from "@tailwindcss/vite"
|
|
84
|
+
import react from "@vitejs/plugin-react"
|
|
85
|
+
import { defineConfig } from "vite"
|
|
86
|
+
|
|
87
|
+
export default defineConfig({
|
|
88
|
+
plugins: [react(), tailwindcss()],
|
|
89
|
+
resolve: {
|
|
90
|
+
alias: {
|
|
91
|
+
"@": path.resolve(__dirname, "./src"),
|
|
92
|
+
},
|
|
93
|
+
},
|
|
94
|
+
})
|
|
95
|
+
VITE_EOF
|
|
96
|
+
|
|
97
|
+
# Step 5: Create minimal index.css for shadcn init to find
|
|
98
|
+
cat > src/index.css << 'CSS_EOF'
|
|
99
|
+
@import "tailwindcss";
|
|
100
|
+
CSS_EOF
|
|
101
|
+
|
|
102
|
+
# Step 6: Run shadcn init (writes components.json, updates deps, creates utils)
|
|
103
|
+
npx --yes "shadcn@${SHADCN_VERSION}" init \
|
|
104
|
+
--base radix \
|
|
105
|
+
--preset nova \
|
|
106
|
+
--css-variables \
|
|
107
|
+
--yes \
|
|
108
|
+
--silent
|
|
109
|
+
|
|
110
|
+
echo "[scaffold-full] shadcn init complete."
|
|
111
|
+
|
|
112
|
+
# Step 7: Merge theme.css if provided
|
|
113
|
+
if [[ -n "$THEME_CSS" && -f "$THEME_CSS" ]]; then
|
|
114
|
+
echo "[scaffold-full] Merging theme from: $THEME_CSS"
|
|
115
|
+
# The shadcn init writes its own :root block into src/index.css.
|
|
116
|
+
# We replace the :root and @theme inline sections with the DESIGN.md-derived ones.
|
|
117
|
+
# Strategy: append our theme.css content after the @import lines.
|
|
118
|
+
# The agent should refine this merge based on actual content.
|
|
119
|
+
|
|
120
|
+
# Extract @import lines from current index.css
|
|
121
|
+
IMPORTS=$(grep -E "^@import" src/index.css || true)
|
|
122
|
+
|
|
123
|
+
# Rebuild index.css: imports + our theme + base layer
|
|
124
|
+
{
|
|
125
|
+
echo "$IMPORTS"
|
|
126
|
+
echo ""
|
|
127
|
+
cat "$THEME_CSS"
|
|
128
|
+
echo ""
|
|
129
|
+
echo "@layer base {"
|
|
130
|
+
echo " * {"
|
|
131
|
+
echo " @apply border-border outline-ring/50;"
|
|
132
|
+
echo " }"
|
|
133
|
+
echo " body {"
|
|
134
|
+
echo " @apply bg-background text-foreground;"
|
|
135
|
+
echo " }"
|
|
136
|
+
echo "}"
|
|
137
|
+
} > src/index.css
|
|
138
|
+
|
|
139
|
+
echo "[scaffold-full] Theme merged into src/index.css"
|
|
140
|
+
fi
|
|
141
|
+
|
|
142
|
+
# Step 8: Create a placeholder App.tsx
|
|
143
|
+
cat > src/App.tsx << 'APP_EOF'
|
|
144
|
+
import "./index.css"
|
|
145
|
+
|
|
146
|
+
export default function App() {
|
|
147
|
+
return (
|
|
148
|
+
<main className="mx-auto max-w-4xl px-4 py-10">
|
|
149
|
+
<header className="mb-8 rounded-xl border bg-card p-5 shadow-sm">
|
|
150
|
+
<p className="mb-2 text-xs font-semibold uppercase tracking-wide text-secondary-foreground">
|
|
151
|
+
Mockup — Variant VARIANT_NUM
|
|
152
|
+
</p>
|
|
153
|
+
<h1 className="text-2xl font-semibold">FEATURE_NAME</h1>
|
|
154
|
+
<p className="mt-2 text-sm text-muted-foreground">
|
|
155
|
+
This is a full-fidelity mockup scaffold. Implement screens and interactions here.
|
|
156
|
+
</p>
|
|
157
|
+
</header>
|
|
158
|
+
|
|
159
|
+
{/* Agent: implement mockup screens below */}
|
|
160
|
+
<section className="rounded-xl border bg-card p-5 shadow-sm" data-ac="AC-TODO">
|
|
161
|
+
<h2 className="text-lg font-semibold">Screen Content</h2>
|
|
162
|
+
<p className="mt-2 text-sm text-muted-foreground">
|
|
163
|
+
Replace this with the actual mockup implementation.
|
|
164
|
+
</p>
|
|
165
|
+
</section>
|
|
166
|
+
</main>
|
|
167
|
+
)
|
|
168
|
+
}
|
|
169
|
+
APP_EOF
|
|
170
|
+
|
|
171
|
+
# Replace placeholders
|
|
172
|
+
sed -i '' "s/VARIANT_NUM/${VARIANT}/g" src/App.tsx
|
|
173
|
+
sed -i '' "s/FEATURE_NAME/${FEATURE}/g" src/App.tsx
|
|
174
|
+
|
|
175
|
+
# Clean up Vite default files
|
|
176
|
+
rm -f src/App.css src/assets/react.svg public/vite.svg
|
|
177
|
+
|
|
178
|
+
popd >/dev/null
|
|
179
|
+
|
|
180
|
+
echo ""
|
|
181
|
+
echo "[scaffold-full] Done. Project created at: $OUTPUT_DIR"
|
|
182
|
+
echo " cd $OUTPUT_DIR"
|
|
183
|
+
echo " $PM run dev"
|