---
base_skill: ui-design
base_skill_version: 3.0.0
mode: extend
---

# ui-design — fidelity-app overlay (example)

> This overlay captures every project-specific opinion that used to live
> hard-coded in the BALDART `ui-design` skill before v3.0.0. Drop it into
> your repo at `.baldart/overlays/ui-design.md` to reproduce the legacy
> behaviour. Adapt freely.
>
> Companion `baldart.config.yml` values (set via `npx baldart configure`):
> ```yaml
> identity:
>   brand_name: "Fidelity"
>   design_philosophy: "Neo-Brutalism"
>   language: it
>   audience_segments: ["customer","merchant","merchant-staff","super-admin"]
> stack:
>   charting:
>     canonical: ["recharts", "@nivo/heatmap"]
>     forbidden: ["chart.js","echarts","victory","visx","d3","observable-plot","tremor"]
>     wrappers_root: "src/components/charts"
> features:
>   has_design_system: true
>   multi_tenant_theming: true
> ```

## Audience segments (project-specific)

The Step "Prerequisites" item 7 menu of audience segments is hard-pinned to:
**Customer, Merchant, Merchant Staff, Super Admin.** Ask the user which one before any design work; refuse to proceed if unstated.

## Tailwind v4 token mechanism (extends "Design System Alignment")

Tailwind CSS v4 is in use (CSS-first, **NO** `tailwind.config.ts`). Token consumption is via CSS custom properties declared in `${paths.global_styles}`. Never hardcode hex colors, shadow pixel tuples, or border-width values — use the CSS variables declared in `${paths.design_system}/tokens-reference.md`.

## Merchant theming pairing rule (multi-tenant)

When rendering any text over a theme-primary background, it MUST pair with the theme-primary-text token:
```html
<span class="bg-[var(--theme-primary)] text-[var(--theme-primary-text,#000)]">…</span>
```
This is non-negotiable per `${paths.design_system}/patterns/merchant-theming.md`. Evaluation FAILS hard on any violation regardless of other scores.

## [OVERRIDE] Charting stack (Prerequisites item 5)

Replaces the generic "consult `stack.charting`" rule. The project enforces:

- **Canonical**: Recharts v3 (via shadcn primitives in `${paths.components_primitives}/chart.tsx`) + `@nivo/heatmap` only.
- **Always propose the Neo-Brutalism wrappers** in `${stack.charting.wrappers_root}/` — `BrutalLineChart`, `BrutalBarChart`, `BrutalDonutChart`, `BrutalHeatmapChart`. Never propose raw Recharts/Nivo.
- **Forbidden** (immediate refusal): chart.js, echarts, victory, visx, d3 standalone, observable-plot, tremor.
- Read `${paths.design_system}/patterns/charting.md` (BLOCKING) before any chart task.
- Reference ADR: `${paths.adrs_dir}/ADR-20260516-charting-stack-standardization.md`.

## [OVERRIDE] Browser open command (Step E + generation.md)

Replaces the generic `open <file>` instruction. The project standardizes on Safari:
```bash
open -a Safari /tmp/prd-design-<slug>/option-a.html
```

## Evaluation — additional thresholds

In addition to the base soglie hard:

- **C3 (Design System) >= 4** when `identity.design_philosophy: "Neo-Brutalism"` — anything else means the prototype reads as generic shadcn rather than brutalist.
- **Themed-surface pairing check**: FAIL on any `bg-[var(--theme-primary)]` without a matching `text-[var(--theme-primary-text,…)]`.
- **Italian-only**: any English UI text (CTA, button label, empty state) is an automatic FAIL.

## Marker labels

In Step C "Marker": use `NUOVO` for new areas, `MODIFICATO` for changed areas. Bordo tratteggiato attorno agli elementi modificati nel layout esistente.
