baldart 5.1.0 → 5.2.0

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

@@ -1,221 +1,44 @@
 ---
 name: frontend-design
-effort: medium
-version: 1.0.0
-description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
+effort: low
+version: 2.0.0
+description: "ROUTER (retired generator, since framework v5.2.0). Historically triggered for building web components, pages, dashboards, landing pages, HTML/CSS layouts, or styling/beautifying any web UI — those triggers still land here, and this skill immediately routes them to the right BALDART surface: /ui-design (design, mockups, prototyping, restyling), /ui-implement (approved mockup → code), the ui-expert agent (direct in-code UI work). Do not follow this skill for design guidance; its design intelligence moved to ui-design/references/ (craft-standards, anti-slop, design-directions)."
 license: Complete terms in LICENSE.txt
 ---
 
-This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
-
-## Project Context
-
-**Reads from `baldart.config.yml`:** `paths.design_system`, `paths.ui_guidelines`, `identity.design_philosophy`, `stack.charting.canonical`, `stack.animation.canonical`.
-**Gated by features:** `features.has_design_system` (when `true`, the BLOCKING reads in the next section are mandatory; when `false`, fall back to `paths.ui_guidelines` alone — the BOLD aesthetic direction is then driven by `identity.design_philosophy` only).
-**Overlay:** loads `.baldart/overlays/frontend-design.md` if present — project-specific aesthetic mandates, forbidden patterns, illustration-motion contract.
-**On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
-
-The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
-
-## Effort
-
-**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
-`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
-reasoning depth for this run — detect it once at kickoff and strip the token
-before consuming user input. Level→behavior mapping, parsing contract, and
-precedence caveats: `framework/agents/effort-protocol.md`.
-
-
-## Design Thinking
-
-Before coding, understand the context and commit to a BOLD aesthetic direction:
-- **Purpose**: What problem does this interface solve? Who uses it?
-- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
-- **Constraints**: Technical requirements (framework, performance, accessibility).
-- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
-
-**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
-
-Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
-- Production-grade and functional
-- Visually striking and memorable
-- Cohesive with a clear aesthetic point-of-view
-- Meticulously refined in every detail
-
-## Frontend Aesthetics Guidelines
-
-Focus on:
-- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
-- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
-- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
-- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
-- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
-
-NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
-
-Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
-
-**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
-
-Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
-
-## MANDATORY Pre-Work Read (project design-system override)
-
-The registry-first cascade below is the consumer view of the SSOT in
-[`framework/agents/design-system-protocol.md`](../../../agents/design-system-protocol.md).
-When the cascade rules diverge between this file and the protocol module,
-the protocol module wins.
-
-When operating inside a repo that ships a design-system SSOT, the generic
-creative guidance above is BLOCKED by the project design-system until the
-reads below are complete. MANDATORY pre-work reads (skipping any of them is
-a protocol violation when the docs exist):
-
-1. **MANDATORY / BLOCKING** — `${paths.design_system}/INDEX.md`. Authoritative component index + Canonical Authority Matrix. Discover existing primitives there BEFORE inventing new ones.
-2. **MANDATORY / BLOCKING** — `${paths.design_system}/tokens-reference.md`. Human-readable token contract (colors, spacing, radius, shadows, typography). Never hardcode hex colors, shadow pixel tuples, or border widths not defined in the design-system doc.
-3. **MANDATORY** — `${paths.design_system}/components/<Name>.md` for every primitive in scope, and `${paths.design_system}/patterns/*.md` (overlays, theming, animations, platform quirks) for the pattern involved.
-4. **MANDATORY / BLOCKING** — `${paths.ui_guidelines}`. Brand philosophy, aesthetic rules, SVG rules, accessibility constraints.
-5. **MANDATORY for generated marketing illustrations/videos** — `the project's illustration-motion pattern doc (listed in `.baldart/overlays/frontend-design.md` if present)` (if your project has one). Canonical illustration language, product-variant vocabulary, and surgical element-by-element video prompt contract.
-
-Non-negotiable constraints typical of mature design-system SSOTs (adapt to your project):
-
-- Token consumption: only via the project's design-token mechanism (e.g. CSS custom properties, Tailwind theme, Stitches tokens). Never hardcode values outside this contract.
-- **Themed-surface text/bg pairing rule (MANDATORY / BLOCKING)** when the design-system defines a primary theme color: any text rendered over the themed primary background MUST pair with the project's theme-primary-text token (e.g. `text-[var(--theme-primary-text,#000)]` on `bg-[var(--theme-primary)]`).
-- Do NOT create new overlay systems if the project already catalogs an overlay decision tree — pick from the existing options.
-- **Chart library (MANDATORY / BLOCKING)** when the project standardizes a chart stack: use only the approved library and the project's wrappers, never call the underlying chart library from feature code. Banned libraries (typical): `chart.js`, `echarts`, `victory`, `visx`, `d3` standalone, `observable-plot`, `tremor`. Exceptions require an ADR.
-
-Within those bounds, creative choices (typography nuance, composition, motion intensity) are welcome — but the design-system token contract and themed-surface pairing are non-negotiable.
-
----
-
-## Performance Gates (Core Web Vitals 2026)
-
-Production-grade frontend is not just "looks good" — it ships within the CWV
-thresholds. Every page / component / route MUST be designed against these
-budgets, not retrofitted after Lighthouse complains.
-
-### Thresholds (p75, CrUX dataset)
-
-| Metric | Good | Poor | What it measures |
-|---|---|---|---|
-| **LCP** | ≤ 2.5s | > 4.0s | Largest Contentful Paint — usually the hero image or H1 |
-| **INP** | ≤ 200ms | > 500ms | Interaction to Next Paint — replaced FID in Mar 2024 |
-| **CLS** | ≤ 0.1 | > 0.25 | Cumulative Layout Shift |
-| TTFB | ≤ 0.8s | > 1.8s | Subset of LCP (~40% of budget) |
-| FCP | ≤ 1.8s | > 3.0s | Diagnostic only |
-
-A page passes CWV when all three (LCP/INP/CLS) are *good* at p75. INP is the
-hardest of the three on JS-heavy apps and the most commonly failed (~43% of
-sites globally).
-
-### LCP image: the only correct pattern
-
-```html
-<!-- in <head> — preload + fetchpriority for the hero -->
-<link rel="preload" as="image"
-      href="/hero.avif"
-      imagesrcset="/hero-800.avif 800w, /hero-1600.avif 1600w"
-      imagesizes="100vw"
-      fetchpriority="high">
-
-<!-- in body — picture with AVIF/WebP/fallback + explicit dimensions -->
-<picture>
-  <source srcset="/hero.avif" type="image/avif">
-  <source srcset="/hero.webp" type="image/webp">
-  <img src="/hero.jpg" alt="..."
-       fetchpriority="high"
-       width="1600" height="900">
-</picture>
-```
-
-**Never** apply `loading="lazy"` to the LCP image. **Never** render the LCP
-image via client-side JS after hydration — server-render it or preload it.
-
-### INP fixes
-
-- Break any task > 50ms into `await scheduler.yield()` chunks (Chrome 129+;
-  fallback `await new Promise(r => setTimeout(r, 0))`).
-- Debounce input handlers to one frame (~16ms) when they trigger expensive
-  recomputes. Throttle scroll/resize to `requestAnimationFrame`.
-- Move CPU-bound work (parsing, transforming, encoding) off the main thread
-  with Web Workers when latency matters.
-- Avoid `setInterval` polling for data — use SWR / React Query / TanStack
-  Query with stale-while-revalidate.
-
-### CLS budget — zero unexpected shift
-
-- Every `<img>`, `<iframe>`, `<video>` declares `width` + `height` or
-  `aspect-ratio` CSS.
-- Web fonts: `font-display: optional` (no FOIT/FOUT shift, accept fallback
-  on first load) OR `size-adjust` + matching `ascent-override` /
-  `descent-override` / `line-gap-override` to produce a metric-compatible
-  fallback font.
-- Skeleton screens mirror the real layout dimensions exactly — a skeleton
-  that's the wrong height *causes* CLS instead of preventing it.
-- Inserted UI (banners, cookie notices, ads) must reserve space upfront via
-  `min-height` — never push existing content down post-paint.
-
-## Modern CSS (2025–2026)
-
-Default to platform features instead of JS shims:
-
-- **Container queries** (`@container` + `container-type: inline-size`) —
-  default for any component that lives in variable-width contexts (sidebar,
-  grid cell, modal). Component decides its own breakpoint, independent of
-  viewport. Use viewport-based `@media` only for app-shell-level layout.
-- **`:has()`** — collapse `useState` that exists *only for styling*
-  (e.g. label color reacting to input invalid state). Never put business
-  logic into `:has()` — only visual reactions to DOM state.
-- **View Transitions API** — `document.startViewTransition()` for SPA
-  navigation and `view-transition-name` for shared-element morphs. See
-  `motion-design/reference/accessibility-and-modern-apis.md` for the full
-  pattern.
-- **Subgrid** — children align to the parent grid without re-declaring
-  tracks. Fixes the long-standing "card content alignment across rows"
-  problem.
-- **Logical properties** — `margin-inline-start` / `padding-block` instead
-  of `margin-left` / `padding-top` whenever the project might add RTL or
-  vertical-writing-mode locales. Free i18n with zero overhead.
-- **`color-mix()`** — derive hover / focus / disabled states from semantic
-  tokens without inventing new tokens
-  (`color-mix(in oklch, var(--color-action-primary) 90%, black)`).
-- **`@scope`** — scope CSS to a subtree without selector specificity wars or
-  CSS-in-JS. Useful when migrating off CSS Modules / styled-components.
-
-## Form quality (always-on requirements)
-
-These apply to every form, every project — they are not "nice to have":
-
-- `<label>` associated to input via `htmlFor` / `id` (never wrap-only — fails
-  some screen readers).
-- `autocomplete=` filled for every personal-data field
-  (`email | tel | given-name | family-name | street-address | postal-code |
-  cc-number | one-time-code` …). Required by WCAG 2.1 SC 1.3.5.
-- Validation **on blur**, not on every keystroke. Re-validate on submit.
-- Error messages are **actionable** ("Email manca @ — esempio:
-  nome@dominio.it"), never generic ("Invalid input").
-- `aria-invalid` + `aria-describedby` linking the input to its error
-  element. Error element has `role="alert"` only when it appears
-  dynamically.
-- `inputMode=` set when it differs from `type` (e.g. `type="text"
-  inputMode="numeric"` for SMS codes — keeps the field text-shaped but
-  triggers the numeric keypad).
-- Paste handling normalizes whitespace and format BEFORE validating
-  (cc-number without spaces, tel without separators).
-- Submit button disabled only **after** a failed attempt — never blocked
-  pre-emptively; users should be allowed to try and receive feedback.
-
----
-
-## Standalone Prototypes and Demos
-
-When the task calls for an interactive HTML prototype, animated demo, slide deck, iOS/app mockup, or design exploration **not tied to the project codebase**, the `huashu-design` skill can supplement or replace this skill. It provides:
-- App Prototype shell (AppPhone state manager, tappable, iPhone frame)
-- Tweaks panel for in-page variants
-- Animation export → MP4/GIF (25fps base, 60fps interpolated)
-- 5 flows × 20 design philosophies for design exploration
-- Playwright click-test validation before delivery
-
-**`huashu-design` is OPTIONAL** — it is a user-installed skill, not shipped with the framework. If it is not present, proceed with this skill alone and notify the user: "huashu-design not found; continuing with frontend-design only. Install huashu-design for advanced prototype tooling."
-
-**Filesystem Rule (ABSOLUTE):** every HTML output/prototype must be written to disk with the `Write` tool BEFORE opening it in a browser or sharing it with the user. Outputting inline code blocks is not sufficient.
+# frontend-design — router (retired generator)
+
+Since framework v5.2.0 this skill no longer generates or styles UI. Its
+design intelligence (aesthetic direction, craft rules, anti-slop bans,
+Performance Gates/CWV, Modern CSS, form quality) was superseded and moved to
+the **`ui-design`** skill's references, which are the single SSOT:
+
+- `ui-design/references/craft-standards.md` — always-on craft + **Performance
+  Gates (CWV 2026)** + Modern CSS + form quality (the sections that used to
+  live in this file).
+- `ui-design/references/anti-slop.md` — the anti-generic-AI Tells catalog.
+- `ui-design/references/design-directions.md` — aesthetic directions, font
+  and palette discipline.
+
+## Route the request (do this instead of proceeding here)
+
+| The task is… | Route to |
+|---|---|
+| Designing, prototyping, exploring options, restyling/redesigning a page or component — any *design decision* work | **`/ui-design`** (the local design studio) |
+| Implementing an ALREADY-APPROVED mockup (image / HTML / Claude Design link / `mockups/_src/`) into the codebase | **`/ui-implement`** |
+| A direct in-code UI change with no new design decision (fix a layout, restyle within the existing language, build a specified component) | delegate to the **`ui-expert`** agent per `AGENTS.md` § delegation (registry-first cascade applies) |
+| Motion/animation specs | **`/motion-design`** |
+| A standalone one-off artifact not tied to this project (poster, demo page) | **`/ui-design`** in exploration regime |
+
+Announce the reroute in one line (e.g. "frontend-design è stato ritirato a
+router — proseguo con /ui-design") and continue seamlessly with the target
+surface. Do NOT stop to ask permission for the reroute; do NOT apply design
+guidance from any earlier version of this file.
+
+## Consumer overlays
+
+If this project carries `.baldart/overlays/frontend-design.md` (aesthetic
+mandates, illustration-motion contract), those opinions belong on the design
+studio now — port them to `.baldart/overlays/ui-design.md` (the `/overlay`
+skill scaffolds it). Until ported, honor them when routing lands on
+`/ui-design`.

package/framework/.claude/skills/gamification-design/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.0.1 — 2026-07-03
+
+- Related Skills: `ui-ux-pro-max` (superseded) sostituito con `ui-design` v2
+  (design-directions + craft-standards references). Framework v5.2.0.
+
 ## 1.0.0 — 2026-07-01
 
 - Baseline: versioning per-skill introdotto al framework v4.82.0.

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

@@ -1,7 +1,7 @@
 ---
 name: gamification-design
 effort: medium
-version: 1.0.0
+version: 1.0.1
 description: Use when designing or analyzing points systems, reward loops, progression mechanics, engagement features, or loyalty programs. Triggers include "points system," "rewards design," "progression," "engagement loop," "battle pass," "loyalty mechanics," "gamification," or "retention hooks." For B2C customer-facing features in this codebase, this skill invokes the hyper-gamification-designer agent.
 ---
 
@@ -133,7 +133,7 @@ Before invoking the agent, verify you have:
 
 - `prd-planning`: For full PRD with gamification section
 - `copywriting`: For reward/achievement messaging
-- `ui-ux-pro-max`: For gamification UI patterns
+- `ui-design`: For designing gamification UI (mockups/options; its `references/design-directions.md` + `craft-standards.md` replace the retired `ui-ux-pro-max`)
 
 ## Project Integration
 

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

@@ -2,9 +2,68 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 2.0.0 — 2026-07-03
+
+**The local design studio.** Root-level refactor (framework v5.2.0): the
+skill absorbs top-of-the-line design intelligence distilled from
+[impeccable](https://github.com/pbakaus/impeccable) (Apache-2.0),
+[taste-skill](https://github.com/Leonxlnx/taste-skill) (MIT) and
+[open-design](https://github.com/nexu-io/open-design) (Apache-2.0), and stops
+depending on superseded external skills. Public step contract A–H is
+UNCHANGED (the `/prd` 3a–3e mapping still holds).
+
+- **BREAKING — external-skill dependencies removed**: `ui-ux-pro-max`
+  (Prerequisite 6, dropped — replaced by the internal references),
+  `huashu-design` (optional prototype engine, dropped — the engine rules now
+  live in `references/generation.md`), `frontend-design` (linked skill,
+  retired to a router at framework level).
+- **NEW Step C.0 — Design Read & Direction Lock** (`references/design-brief.md`):
+  register (brand/product), regime (in-context/exploration), the three dials
+  (VARIANCE/MOTION/DENSITY), two-altitude slop test, scene sentence,
+  color-commitment axis, anti-references, ONE-question ambiguity rule,
+  rotation check. Persisted in the state file.
+- **NEW `references/design-directions.md`**: 12-direction aesthetic menu,
+  color commitment axis, reflex-reject lists (LILA rule, premium-consumer
+  beige ban, cream/sand band, serif discipline, font reflex pool + rotation).
+- **NEW `references/craft-standards.md`**: always-on craft rules (tracking
+  table, three-weight system, color proportions + accent rationing ≤2/screen,
+  layout-family diversity, 8-state taxonomy + loading thresholds, Laws-of-UX
+  numbers, 100/300/500 motion rule, curve-vs-spring) — numeric ranges cite
+  `design-system-protocol.md` § Reference Tables. **Canonical new home of the
+  Performance Gates (CWV 2026), Modern CSS and Form-quality sections**
+  migrated from the retired `frontend-design` generator.
+- **NEW `references/anti-slop.md`**: the Tells catalog — absolute bans,
+  rationed patterns (eyebrow ≤ ceil(sections/3), etc.), layout/copy tells,
+  every ban with a declared-override path.
+- **NEW `scripts/craft-check.mjs`**: deterministic anti-slop/craft gate
+  (~22 rules, zero deps, `--json`, `--strict-palette`), run by the generator
+  as self-check and by Step D as Gate 0. Identical on Claude and Codex.
+- **Step D rewritten** (`references/evaluation.md`): Gate 0 (craft-check,
+  fail-fast, output hidden from lenses) + **Lens A = `ui-quality-critic`**
+  (true evaluator diversity — a different agent definition, rubric SSOT in
+  `design-system-protocol.md` § Design Quality Rubric) + **Lens B = fresh
+  `ui-expert`** (brief/context conformance B1–B5, evidence-cited scoring,
+  worst-sustained-band). Honest **degraded mode** on non-multimodal runtimes
+  (mandatory `⚠️ DEGRADED` banner). Max 5 iterations unchanged.
+- **Generation rewritten** (`references/generation.md`): token-first scaffold
+  (project tokens embedded in `:root` — the mockup speaks the project token
+  language, mirroring the Claude Design channel), `data-region` annotations
+  (surgical iteration + deterministic inventory join), real-content
+  discipline (image source ladder, copy self-audit, states-as-content),
+  responsive-by-construction (375px is evaluated), generator craft self-check.
+- **Routing fix**: frontmatter `description` rewritten to win skill routing
+  for design/prototype/restyle work (explicit supersession of
+  `frontend-design`/`ui-ux-pro-max`; IT+EN triggers; explicit NOT-list →
+  `/ui-implement`, `ui-expert`, `/motion-design`).
+- **Runtime portability**: new § citing
+  `agents/runtime-portability-protocol.md` (spawn/decision-gate bindings);
+  Codex degradation documented instead of silent.
+- Codex parity: **portable** (same SKILL.md bundle; zero-dep script; visual
+  lenses degrade honestly with banner).
+
 ## 1.1.0 — 2026-07-02
 
-- **Analysis-profile contract (framework v4.94.0)**: Step B adjacent-UI analysis passes `PROFILE=ui OUTPUT=terse` to `codebase-architect` (registry-cascade-first per `framework/agents/analysis-profiles.md`).
+- **Analysis-profile contract (framework v4.94.0)**: Step B adjacent-UI analysis passes `PROFILE=ui OUTPUT=terse` a `codebase-architect` (registry-cascade-first per `framework/agents/analysis-profiles.md`).
 
 ## 1.0.0 — 2026-07-01