baldart 3.40.0 → 4.0.0

package/framework/.claude/skills/simplify/SKILL.md

@@ -65,11 +65,12 @@ Review the same changes for hacky patterns:
 6. **Unnecessary JSX nesting**: wrapper Boxes/elements that add no layout value — check if inner component props (flexShrink, alignItems, etc.) already provide the needed behavior
 7. **Unnecessary comments**: comments explaining WHAT the code does (well-named identifiers already do that), narrating the change, or referencing the task/caller — delete; keep only non-obvious WHY (hidden constraints, subtle invariants, workarounds)
 
-### Agent 2b: Design System SSOT Compliance (MANDATORY for UI refactors)
+#### Agent 2 — Design System SSOT Compliance sub-checklist (MANDATORY for UI refactors)
 
-When the diff includes files under `src/components/`, `src/app/**/*.tsx`, or any
-`.css`/`.module.css`, the simplify pass MUST NOT introduce hardcoded design values while
-refactoring. Run this as part of the quality review:
+This is part of Agent 2's single task (NOT a separate fourth parallel agent — the three agents in
+Step 2 are Agents 1, 2, 3). When the diff includes files under `${paths.components_root}/`,
+`${paths.components_root}/**/*.tsx`, or any `.css`/`.module.css`, the simplify pass MUST NOT introduce
+hardcoded design values while refactoring. Agent 2 runs this as part of its quality review:
 
 1. Read `${paths.design_system}/INDEX.md` (component index + Canonical Authority Matrix + Quick
    rules MUST) before rewriting any component.
@@ -112,23 +113,32 @@ If no issues are found, say so and stop. Do not invent problems.
 For each finding, apply the fix directly:
 
 - **Exact duplicates**: Delete the new code, import the existing version, update all references.
-- **Near duplicates**: Extract a shared function/component/hook to the appropriate shared directory (`src/lib/`, `src/hooks/`, `src/components/shared/`). Update all call sites to use the shared version.
+- **Near duplicates**: Extract a shared function/component/hook to the project's shared directory resolved from `baldart.config.yml` (see "When extracting shared code" below). Update all call sites to use the shared version.
 - **Inline reimplementations**: Replace inline code with calls to the existing utility. Add imports.
 - **Quality issues**: Apply the fix inline (remove redundant state, simplify JSX nesting, replace string literals with constants, etc.).
 - **Efficiency issues**: Apply the fix inline (parallelize independent calls, add change-detection guards, batch reads, etc.).
 
-When extracting shared code:
-- Place utilities in `src/lib/` (whichever module is closest in domain)
-- Place shared components in `src/components/shared/` or `src/components/ui/`
-- Place shared hooks in `src/hooks/`
-- Do not create new directories if equivalent ones already exist
+When extracting shared code, write to the SAME `${paths.*}` keys the review phase (Step 2) reads from `baldart.config.yml` — never hardcode a fallback that bypasses config. A consumer whose utilities live under `packages/shared/utils/` must get the extracted file there, not in a baked-in `src/lib/`:
+- Place shared components under `${paths.components_root}/shared/` (or `${paths.components_primitives}/` for a primitive).
+- Place utilities and hooks under the project's utility/hook roots as declared in the project overlay (`.baldart/overlays/simplify.md` lists `paths.lib_dir` / `paths.hooks_dir` or the project's equivalents).
+- If the relevant key is missing or empty, ASK the user where the shared code should live — do not assume `src/lib/` / `src/hooks/` / `src/components/shared/`. See `framework/agents/project-context.md` § 3.
+- Do not create new directories if equivalent ones already exist.
 
 ## Step 5: Verify
 
-Run the linter and type checker:
+These static checks run AFTER Step 4 has mutated code — a pre-fix pass would not cover the post-fix
+code, so re-running them here is mandatory whenever Step 4 changed anything.
+
+Run the linter (use the project's lint command):
 
 ```
 npm run lint
+```
+
+Run the type checker as its own blocking step ONLY when `stack.language` includes `typescript`
+(skip otherwise — `tsc` is meaningless on a non-TS project):
+
+```
 npx tsc --noEmit
 ```
 
@@ -138,6 +148,6 @@ Run the project's test suite (if tests exist):
 npm test
 ```
 
-If tests or lint fail, fix the issues. The codebase must be in a passing state when you're done.
+If tests, lint, or (where applicable) tsc fail, fix the issues. The codebase must be in a passing state when you're done.
 
 When done, briefly summarize what was fixed (or confirm the code was already clean).

package/framework/.claude/skills/ui-design/SKILL.md

@@ -11,7 +11,8 @@ design with a structured UI Element Inventory.
 
 **Architecture principle:** The generator never evaluates its own output.
 Evaluation is always performed by a separate agent with fresh context.
-(Ref: Anthropic "Harness Design for Long-Running Apps")
+[DESIGN-CHOICE: a fresh-context evaluator avoids the generator rationalizing its
+own mockups — separating generation from scoring keeps the quality gate honest.]
 
 ## Project Context
 
@@ -106,7 +107,14 @@ Read [references/generation.md](references/generation.md) § Context Capture.
 
 Read [references/generation.md](references/generation.md).
 
-**MANDATORY:** invoke the `huashu-design` skill before generating any HTML. It provides the HTML prototype engine (React+Babel or vanilla+Tailwind CDN, Tweaks panel, App Prototype shell with AppPhone state manager, Playwright click validation, animated output). Follow its rules for the prototype type in scope.
+**OPTIONAL (graceful degradation):** `huashu-design` is a user-installed skill, NOT shipped with the
+framework. If it is installed, invoke it before generating any HTML — it provides the HTML prototype
+engine (React+Babel or vanilla+Tailwind CDN, Tweaks panel, App Prototype shell with AppPhone state
+manager, Playwright click validation, animated output); follow its rules for the prototype type in
+scope. If it is NOT installed, proceed without it: emit a one-line notice ("huashu-design not
+installed — generating HTML mockups directly") and have `ui-expert` produce the HTML mockups using
+the generation rules in `references/generation.md` plus a Tailwind CDN scaffold. Never block the
+design run on huashu-design's absence.
 
 **Filesystem rule (ABSOLUTE):** every HTML file MUST be written to disk with the `Write` tool at `/tmp/prd-design-<slug>/option-X.html` BEFORE opening in a browser. Outputting inline code blocks is not sufficient.
 
@@ -116,7 +124,7 @@ Invoke `ui-expert` agent with:
 - Codebase-architect findings
 - 21st.dev catalog categories
 - Full generation rules from the reference
-- `huashu-design` prototype rules loaded above
+- `huashu-design` prototype rules loaded above (only if the skill is installed; otherwise omit)
 - `identity.design_philosophy` and `identity.language` to drive aesthetic and copy register
 
 Output: 3 HTML files written to `/tmp/prd-design-<slug>/` via `Write` tool.
@@ -125,10 +133,14 @@ Output: 3 HTML files written to `/tmp/prd-design-<slug>/` via `Write` tool.
 
 Read [references/evaluation.md](references/evaluation.md).
 
-Invoke a **separate** `code-reviewer` agent (NOT the same agent that generated):
+Invoke a **separate, fresh-context `ui-expert` agent** (a NEW instance — NOT the `ui-expert` that
+generated in Step C). `ui-expert` is the right evaluator because the rubric scores design-quality
+criteria (visual hierarchy, information density, mobile-first layout) — a code-quality reviewer would
+apply a code-correctness lens and miss the design criteria entirely. The GAN separation is preserved
+by using a distinct instance with no memory of the generation pass.
 - Pass the 3 HTML files
 - Pass the context screenshots as reference
-- Pass the evaluation rubric (7 criteria, scoring 1-5, hard thresholds)
+- Pass the evaluation rubric from [references/evaluation.md](references/evaluation.md) (7 criteria, scoring 1-5, hard thresholds) — the evaluator must read that reference, it does not know the rubric natively
 - Request: produce evaluation report at `/tmp/prd-design-<slug>/evaluation-report.md`
 
 **If any option FAIL:** send feedback to generator, re-generate, re-evaluate. Max 5 iterations per option.
@@ -161,7 +173,14 @@ Invoke a **separate** `code-reviewer` agent (NOT the same agent that generated):
 
 Read [references/inventory.md](references/inventory.md).
 
-1. Copy approved HTML to `${paths.prd_dir}/<slug>/design.html` (if `features.has_prd_workflow: true`; otherwise ask the user where to persist the design). **When invoked from `/prd` (since v3.22.0), prefix this with `WORKING_DIRECTORY` — see the "Working Directory" section near the top of this file.** Concrete absolute target: `<WORKING_DIRECTORY>/<paths.prd_dir>/<slug>/design.html`.
+1. Copy approved HTML to a deterministic canonical path so downstream steps can find it without asking:
+   - `features.has_prd_workflow: true` → `${paths.prd_dir}/<slug>/design.html`.
+   - `features.has_prd_workflow: false` → the framework default `.baldart/designs/<slug>/design.html`
+     (create the directory if missing). Do NOT ask the user for an arbitrary runtime location — a
+     non-recorded path breaks any downstream `/prd` / `/new` step that expects the design at a known
+     location. (The user may override via an overlay-declared `paths.designs_dir`, but the default is
+     deterministic.)
+   **When invoked from `/prd` (since v3.22.0), prefix the chosen relative path with `WORKING_DIRECTORY` — see the "Working Directory" section near the top of this file.** Concrete absolute target (prd-workflow case): `<WORKING_DIRECTORY>/<paths.prd_dir>/<slug>/design.html`.
 2. Extract UI Element Inventory (sprint contract).
 3. Update state file with chosen option, design decisions, component lists.
 4. Clean up `/tmp/prd-design-<slug>/`.
@@ -255,7 +274,7 @@ Provide: triggering action, affected element, desired feedback, accessibility re
 
 | Skill | When |
 |-------|------|
-| `huashu-design` | **MANDATORY in Step C** — HTML prototype engine, App Prototype shell, Tweaks, Playwright validation, MP4/GIF export |
+| `huashu-design` | **OPTIONAL in Step C** (user-installed, not shipped) — HTML prototype engine, App Prototype shell, Tweaks, Playwright validation, MP4/GIF export. If installed, use it; else generate HTML mockups directly with a notice |
 | `ui-ux-pro-max` | Before substantial design for design intelligence |
 | `frontend-design` | To translate design into production code |
 | `webapp-testing` | For browser verification with Playwright |

package/framework/.claude/skills/webapp-testing/SKILL.md

@@ -123,12 +123,14 @@ System SSOT is a first-class test dimension:
 2. Write assertions that reflect component doc expectations — variant-specific classes,
    required props, accessibility attributes. Example: a "primary" button test should assert
    the tokens / classes the component doc defines for that variant.
-3. For merchant-themed surfaces, validate token pairs from
-   `the project's theming pattern doc (listed in `.baldart/overlays/ui-design.md`)` (bg + matching text token) rather than
+3. For themed surfaces (when `features.multi_tenant_theming: true`), validate token pairs from the
+   project's theming pattern doc — `${paths.design_system}/patterns/<theme>.md` (the exact filename is
+   declared in `.baldart/overlays/ui-design.md`) — asserting bg + matching text token rather than
    specific hex.
 4. Motion-sensitive screens MUST include a reduced-motion pass (emulate via
-   `page.emulate_media(reduced_motion='reduce')`) per
-   `the project's motion pattern doc (listed in `.baldart/overlays/ui-design.md`)`.
+   `page.emulate_media(reduced_motion='reduce')`) per the project's motion pattern doc —
+   `${paths.design_system}/patterns/animations.md` (or the motion doc declared in
+   `.baldart/overlays/ui-design.md`).
 
 ## Best Practices