# Component Discovery

Cascade obbligatoria prima di proporre o creare qualsiasi componente UI.

> Paths in this file resolve from `baldart.config.yml`. See
> `framework/agents/project-context.md` § 4.

## Step 1 — Cerca nel progetto

1. Cerca in `${paths.components_root}` componenti riutilizzabili.
2. Controlla `${paths.components_primitives}` per primitive (Button, Card, Badge, etc.).
3. Controlla cartelle di dominio derivate da `identity.audience_segments` (es. `${paths.components_root}/<segment>/`). Se `audience_segments` è vuoto, salta questo passaggio.
4. Preferisci estendere o comporre un componente esistente piuttosto che duplicare.

## Step 2 — Cerca nel catalogo 21st.dev

Prima di creare un componente da zero, controlla la libreria community.

1. Se il progetto traccia un catalogo locale (per esempio `${paths.references_dir}/21st-dev-catalog.md`), leggilo. Altrimenti vai direttamente al sito.
2. **Freshness check:** confronta `last_updated` nel frontmatter con oggi.
   - Se più vecchio di 15 giorni → esegui il **Catalog Refresh** (sotto).
   - Se fresco → continua.
3. Trova la categoria rilevante e naviga l'URL 21st.dev linkato.
4. Se esiste un componente adatto, installa:
   ```bash
   npx shadcn@latest add "https://21st.dev/r/<author>/<component-slug>"
   ```
5. Dopo l'installazione, **adatta al design system del progetto**:
   - Token-compliance: usa i token definiti in `${paths.design_system}/tokens-reference.md` (quando `features.has_design_system: true`).
   - Stilistica: applica le regole estetiche di `identity.design_philosophy` come specificate in `${paths.ui_guidelines}` e nell'overlay `.baldart/overlays/ui-design.md` (se presente).
   - Multi-tenant: se `features.multi_tenant_theming: true`, applica la regola di pairing themed text/bg del progetto.
   - Touch target: minimo 44x44px.
6. Per **pagine landing/marketing**: i componenti possono essere usati con adattamento minimo perché in genere non richiedono il design system completo. Consulta l'overlay del progetto per la regola esatta.

## Step 3 — Crea da zero (ultima risorsa)

Solo se non esiste né nel progetto né su 21st.dev:

- Posiziona il nuovo componente nella cartella shared o di dominio corretta (sotto `${paths.components_root}`).
- Segui `${paths.ui_guidelines}` per tutte le decisioni stilistiche.
- Consuma i token definiti in `${paths.design_system}/tokens-reference.md` (quando `features.has_design_system: true`).

## Catalog Refresh Protocol

Quando il catalogo è stale (>15 giorni da `last_updated`):

1. Usa `playwright-skill` per aprire gli URL delle categorie ad alta rilevanza (buttons, cards, tables, forms, heroes, charts, calendars).
2. Screenshot di ogni pagina ed estrai conteggi aggiornati e nuovi componenti notevoli.
3. Aggiorna il catalogo locale (es. `${paths.references_dir}/21st-dev-catalog.md`):
   - Aggiorna numeri "Est. Count".
   - Aggiungi nuovi componenti notevoli con comandi di installazione diretti.
   - Aggiorna `last_updated` a oggi.
   - Imposta `next_refresh_due` a oggi + 15 giorni.
4. Procedi con la ricerca dopo il refresh.
