@semplice-studio/pa-design-system 0.1.1 → 0.3.0

package/docs/layouts.md

@@ -0,0 +1,297 @@
+# Layout primitives — composing pages with `@semplice-studio/pa-design-system`
+
+> **Audience:** developers building Vue / Nuxt consumer apps on top of `@semplice-studio/pa-design-system`. This guide documents the `.pa-*` utility-class layer shipped in **v1.35** alongside the existing token vocabulary.
+
+## TL;DR
+
+Import the bundled stylesheet **once** in your app entry. You get tokens + layout classes through a single import:
+
+```ts
+// app.vue / main.ts / layouts/default.vue
+import '@semplice-studio/pa-design-system/tokens.css'
+```
+
+Compose pages from three layers:
+
+1. **Tokens** — `var(--pa-color-*)`, `var(--pa-space-*)`, `var(--pa-font-*)` etc. (see [`design-system.md`](./design-system.md) §3).
+2. **Layout classes** — `.pa-page-frame`, `.pa-container`, `.pa-section`, `.pa-grid-3` etc. (this document, §1–§6).
+3. **Components** — `<PaButton>`, `<PaHero>`, `<PaCard>` etc. (see [`design-system.md`](./design-system.md) §4 component registry).
+
+Page chrome (frame / container / sections / grids) → use a class. Visual choices (color / spacing / radius) → use a token. Interactive behavior (button, modal, drawer) → use a component.
+
+## 1. The page chrome
+
+Every page starts with the same three-layer chrome: an outer **frame** clipping the design at 1280 px, a centered **container** capped at 1168 px, and (optionally) a **narrow** band for centered content like auth cards or article bodies.
+
+```vue
+<template>
+  <div class="pa-page-frame">
+    <PaHeaderDesktop … />
+
+    <main id="main">
+      <div class="pa-container">
+        <PaHero … />
+      </div>
+
+      <section class="pa-container pa-section">
+        <!-- regular content section -->
+      </section>
+
+      <section class="pa-section pa-section--tint">
+        <div class="pa-container">
+          <!-- band content -->
+        </div>
+      </section>
+    </main>
+
+    <PaFooter … />
+  </div>
+</template>
+```
+
+| Class | Max-width | Use |
+|---|---|---|
+| `.pa-page-frame` | 1280 px | Wraps the entire page. White background. |
+| `.pa-container` | 1168 px | Centered content column. 16 px side gutter. |
+| `.pa-narrow` | 720 px | Narrow band for CTAs, banners, search inputs. |
+| `.pa-narrow--xs` | 480 px | Auth card width. |
+| `.pa-narrow--prose` | 880 px | Long-form article body / FAQ. |
+
+### Frame vs container vs narrow
+
+- **Frame** is the *page* boundary. Background, max-width, centered.
+- **Container** is the *column* inside the frame. It gives content a consistent 1168 px reading column and a uniform 16 px gutter.
+- **Narrow** is for centered content that should not span the full container width — auth cards, banners, prose articles.
+
+A common pattern: full-bleed gradient or tint band as the section, container inside for content alignment, narrow inside the container for centered focus content (see § 2).
+
+## 2. Sections and bands
+
+Sections give pages their vertical rhythm. A `.pa-section` is one band: 32 / 16 padding default, with `--lg` modifier for the more spacious 48 / 16 default. Add a single `--variant` modifier for the band background:
+
+| Class | Background |
+|---|---|
+| `.pa-section` (no variant) | none |
+| `.pa-section--tint` | `--pa-color-bg-primary-light-40` (soft blue tint) |
+| `.pa-section--dark` | `--pa-color-bg-primary-dark-120` + white text |
+| `.pa-section--gradient` | 135° from `--pa-color-bg-primary-dark-110` to `--pa-color-primary` + white text |
+
+```vue
+<!-- Full-bleed tint band with constrained content -->
+<section class="pa-section pa-section--tint pa-section--lg">
+  <div class="pa-container">
+    <PaTitleBar title="In evidenza" variant="light" />
+    <div class="pa-grid-3">
+      <PaCard … />
+    </div>
+  </div>
+</section>
+```
+
+```vue
+<!-- Gradient hero / CTA band -->
+<section class="pa-section pa-section--gradient pa-section--lg">
+  <div class="pa-narrow">
+    <h2>Pronto a digitalizzare il tuo Ente?</h2>
+    <PaButton variant="primary">Richiedi demo</PaButton>
+  </div>
+</section>
+```
+
+**Vertical rhythm rule of thumb:** use `.pa-section` (32 / 16) for regular bands and `.pa-section--lg` (48 / 16) for hero-band-like sections (top of page, conversion-focused CTAs, banded backgrounds). Reach for `--pa-space-2xl-plus` (64 px) only at the bottom of the page for the closing-section breathing room.
+
+## 3. Grids and stacks
+
+Two families of layout helpers: **grids** (2D, equal columns) and **stacks** (1D flex column with token-spaced gap).
+
+### Grids
+
+```vue
+<div class="pa-grid-3">
+  <PaCard v-for="…" />
+</div>
+```
+
+| Class | Layout |
+|---|---|
+| `.pa-grid-2` / `-3` / `-4` / `-6` | N equal `minmax(0, 1fr)` columns + `--pa-space-sm` gap |
+| `.pa-split` | Two equal columns + `--pa-space-xl` gap (use for prominent 1-1 feature pairs) |
+| `.pa-layout-sidebar` (default `--md`) | Main column + 320 px sidebar + `--pa-space-2xl` gap |
+| `.pa-layout-sidebar--sm` | Sidebar narrows to 280 px (article-page pattern) |
+| `.pa-field-full-row` | Grid utility — child spans `grid-column: 1 / -1`. Use inside `.pa-grid-2` form layouts. |
+
+### Stacks
+
+A stack is a `flex; flex-direction: column; gap: var(--pa-space-N)`. Use stacks instead of stacking `margin-top` on children.
+
+| Class | Gap |
+|---|---|
+| `.pa-stack-xs` | `--pa-space-xs` (8) |
+| `.pa-stack-sm` | `--pa-space-sm` (16) |
+| `.pa-stack-md` | `--pa-space-md` (24) |
+| `.pa-stack-lg` | `--pa-space-lg` (32) |
+| `.pa-stack-xl` | `--pa-space-xl` (40) |
+
+```vue
+<div class="pa-stack-sm">
+  <PaInput … />
+  <PaInput … />
+  <PaSelect … />
+</div>
+```
+
+## 4. Surfaces
+
+| Class | Visual |
+|---|---|
+| `.pa-panel` | White background, 1 px `--pa-color-border-subtle` border, smooth radius, 32 px padding. Use for form cards, content panels, contact cards. |
+| `.pa-tint-card` | Light-tint background, smooth radius, 24 px padding. Use for sidebars, signature blocks, info callouts. |
+| `.pa-tint-card--sticky` | Adds `position: sticky; top: var(--pa-space-md)`. Use for article-page table-of-contents sidebars. |
+
+```vue
+<!-- Form panel -->
+<form class="pa-panel" @submit.prevent="…">
+  <div class="pa-grid-2">
+    <PaInput … />
+  </div>
+  <div class="pa-form-action-bar">
+    <PaButton variant="ghost">Annulla</PaButton>
+    <PaButton variant="primary">Invia</PaButton>
+  </div>
+</form>
+
+<!-- Sticky article sidebar -->
+<aside>
+  <div class="pa-tint-card pa-tint-card--sticky">
+    …
+  </div>
+</aside>
+```
+
+### Dividers
+
+`.pa-divider` is a 1 px horizontal rule using `--pa-color-border-subtle`. `.pa-divider--text` is the same rule with a centered text label ("oppure", "or", "—"):
+
+```vue
+<hr class="pa-divider" />
+
+<div class="pa-divider--text">oppure</div>
+```
+
+### Form chrome
+
+`.pa-form-action-bar` is the standard right-aligned action footer for forms. Includes a subtle top border + token-spaced padding.
+
+```vue
+<form class="pa-panel">
+  …
+  <div class="pa-form-action-bar">
+    <PaButton variant="ghost">Annulla</PaButton>
+    <PaButton variant="primary" type="submit">Invia</PaButton>
+  </div>
+</form>
+```
+
+## 5. Typography helpers
+
+| Class | Effect |
+|---|---|
+| `.pa-eyebrow` | Uppercase section label — 13 px / weight 600 / `letter-spacing 0.04em` / muted color. Pattern repeated above every section heading. |
+| `.pa-eyebrow--sm` | 12 px variant for tighter contexts (info-strip cells). |
+
+```vue
+<p class="pa-eyebrow">Sezione del sito</p>
+<h2>Sezione</h2>
+```
+
+## 6. Compositional helpers
+
+Multi-element patterns recurring across content-heavy pages. Each helper ships as a single class — no need to re-derive the CSS in every consumer project.
+
+| Class | Use |
+|---|---|
+| `.pa-prose` | Wraps article-body content. Scopes typography for nested `h2` / `h3` / `p` / `ul` / `ol` / `figure` / `figcaption`. `scroll-margin-top` on headings supports anchor-TOC navigation. |
+| `.pa-blockquote` | Left-bordered tint blockquote. Italic. |
+| `.pa-stat` + `.pa-stat__value` + `.pa-stat__label` | Big-number stat block. Value consumes the h1 token group; label consumes `--pa-font-small-*` + `--pa-color-text-muted`. |
+| `.pa-info-strip` | Bordered horizontal cell row with vertical dividers between children. Children flex equally. |
+| `.pa-map-placeholder` | 320 px tall gradient placeholder block. (See **Known gaps** below.) |
+| `.pa-article-meta` | Article-header meta row. Flex-wrap, `--pa-space-sm` gap, `--pa-font-small-*` typography, muted color, bottom rule. |
+| `.pa-byline` | Avatar + name signature block. |
+| `.pa-tag-cloud` | Flex-wrap row + `--pa-space-xs` gap. Use for tag / chip / pill groups. |
+| `.pa-icon-circle-sm` / `-md` / `-lg` / `-xl` | 28 / 40 / 48 / 64 px circular icon containers with `border-radius: 50%`. |
+
+### Prose example
+
+```vue
+<article class="pa-container">
+  <div class="pa-prose">
+    <h2 id="sintesi">In sintesi</h2>
+    <p>…</p>
+
+    <blockquote class="pa-blockquote">«…».</blockquote>
+
+    <h2 id="dettagli">Dettagli</h2>
+    <ul>
+      <li>…</li>
+    </ul>
+  </div>
+</article>
+```
+
+### Info-strip example
+
+```vue
+<div class="pa-info-strip">
+  <div>
+    <p class="pa-eyebrow pa-eyebrow--sm">Data</p>
+    <div>2 giugno 2026</div>
+  </div>
+  <div>
+    <p class="pa-eyebrow pa-eyebrow--sm">Orario</p>
+    <div>10:00 – 18:00</div>
+  </div>
+</div>
+```
+
+### Stat example
+
+```vue
+<section class="pa-section pa-section--dark pa-section--lg">
+  <div class="pa-container">
+    <div class="pa-grid-4">
+      <div v-for="s in stats" class="pa-stat">
+        <div class="pa-stat__value">{{ s.value }}</div>
+        <div class="pa-stat__label">{{ s.label }}</div>
+      </div>
+    </div>
+  </div>
+</section>
+```
+
+## 7. What is **not** in this layer
+
+The `.pa-*` utility-class layer is **layout primitives only** — page chrome, sections, grids, stacks, common surfaces, and a handful of compositional patterns. Reach for a `Pa*` **component** when you need:
+
+- Interactive behavior — `PaButton`, `PaModal`, `PaDrawer`, `PaSearchBar`, `PaTabs`, `PaCarousel`, `PaAccordion`, `PaPagination`.
+- Composed page-level chrome — `PaHeaderDesktop`, `PaHeaderMobile`, `PaFooter`, `PaHero`, `PaTitleBar`, `PaCard`, `PaBreadcrumb`, `PaStepProgressBar`.
+- Form fields — `PaInput`, `PaSelect`, `PaTextarea`, `PaCheckbox`, `PaRadioGroup`, `PaFileUpload`, `PaDatePicker`, `PaRangePicker`, `PaTimePicker`, `PaMonthPicker`, `PaYearPicker`.
+- Status surfaces — `PaTag`, `PaChip`, `PaToggle`, `PaBanner`, `PaTable`, `PaProgressBar`, `PaImage`.
+
+Full component registry: [`design-system.md`](./design-system.md) §4.
+
+## 8. Known gaps
+
+Two literals remain inline in `layout.css` because there is no matching token yet:
+
+- **Icon-circle dimensions** — `.pa-icon-circle-sm/-md/-lg/-xl` use literal 28 / 40 / 48 / 64 px. A `--pa-size-icon-*` token group is intentionally deferred until a wider sizing scale lands.
+- **Map-placeholder gradient stops** — `.pa-map-placeholder` uses `linear-gradient(135deg, #E0E8F1 0%, #C6D5E5 100%)` inline. A `--pa-gradient-placeholder-light` token is deferred for the same reason — there is currently only one consumer and no broader gradient vocabulary to extend.
+
+Both gaps are flagged in the source file. When a future release adds the missing tokens, the literals will be swapped out.
+
+## 9. Reference
+
+Every shipped class has a live preview under **design system → Layout** in Histoire (`pnpm dev`). Use it as the canonical visual reference.
+
+For the historical context behind v1.35 — what the templates looked like before, which patterns were duplicated where, why the token gaps were filled the way they were — see [`docs/templates-audit.md`](../templates-audit.md).
+
+For consumer-facing copy-paste references of how full pages compose, browse the 11 templates under `src/templates/*/` in Histoire (`pages` group): they're refactored to demonstrate the layer, with zero inline hex / px literals where tokens exist.

package/docs/page-composition-examples.md

@@ -0,0 +1,286 @@
+# Page composition examples — @semplice-studio/pa-design-system
+
+> Distilled from the 11 reference page templates in `src/templates/` (LandingPage, SearchListPage, DashboardPage, MultiStepFormPage, ArticleDetailPage, EventDetailPage, ContactPage, LoginPage, MarketingPage, OfficeDetailPage, ServiceInfoPage). Read this before composing a page; see [`layouts.md`](layouts.md) for the full `.pa-*` utility reference and [`public-surface.md`](public-surface.md) for component APIs.
+>
+> Conventions in the snippets: imports use the published package; classes **not** prefixed `pa-` are page-local (define them in your page's scoped styles).
+
+## The canonical page skeleton
+
+Every page follows the same frame: `.pa-page-frame` → header → `<main id="main">` → footer. Sections inside `main` are either a plain `.pa-container` (1168 px column) or a full-bleed `.pa-section` band with a `.pa-container` inside (for tinted/dark/gradient backgrounds).
+
+```vue
+<script setup lang="ts">
+import {
+  PaHeaderDesktop, PaHero, PaCarousel, PaCard, PaButton, PaFooter,
+} from '@semplice-studio/pa-design-system'
+</script>
+
+<template>
+  <div class="pa-page-frame">
+    <PaHeaderDesktop :logged-in="loggedIn" :main-nav="mainNav"
+                     :languages="languages" current-language="ita" />
+
+    <main id="main">
+      <!-- plain constrained section -->
+      <div class="pa-container">
+        <PaHero title="Benvenuti nel portale del Comune"
+                subtitle="Servizi e informazioni per cittadini, imprese e visitatori" />
+      </div>
+
+      <!-- constrained section with heading + rhythm -->
+      <section class="pa-container pa-section pa-section--lg">
+        <h2 class="pa-section-title">In Evidenza</h2>
+        <PaCarousel :items-per-page="3" label="Servizi in evidenza">
+          <PaCard v-for="(h, i) in highlights" :key="i" typology="portrait" v-bind="h" />
+        </PaCarousel>
+      </section>
+
+      <!-- full-bleed tinted band, content constrained inside -->
+      <section class="pa-section pa-section--tint pa-section--lg">
+        <div class="pa-container"><!-- … --></div>
+      </section>
+    </main>
+
+    <PaFooter :sitemap="footerSitemap" :address="footerAddress"
+              :socials="footerSocials" copyright="© 2026 Comune. Tutti i diritti riservati." />
+  </div>
+</template>
+```
+
+Widths: `.pa-page-frame` 1280 px outer · `.pa-container` 1168 px + 16 px gutters · `.pa-narrow` 720 px (`--xs` 480, `--prose` 880) · `.pa-section` 32 px vertical padding (`--lg` 48 px).
+
+## Section patterns
+
+### Hero with CTA (Landing, ServiceInfo, Event, Marketing…)
+
+```vue
+<div class="pa-container">
+  <PaHero title="Carta d'identità elettronica" subtitle="Documento di riconoscimento"
+          body="La Carta d'Identità Elettronica (CIE)…"
+          :image-src="heroImage" image-alt="Documento d'identità elettronica"
+          image-ratio="3:2" image-position="right">
+    <template #cta>
+      <PaButton variant="primary">
+        <template #icon-left><PaIcon name="calendar-blank" size="sm" /></template>
+        Prenota appuntamento
+      </PaButton>
+      <PaButton variant="secondary">Maggiori informazioni</PaButton>
+    </template>
+  </PaHero>
+</div>
+```
+
+### Card grid / carousel (Landing, SearchList, Dashboard)
+
+Static grid → `.pa-grid-3` (or `-2`/`-4`) of `PaCard`. Scrollable strip → `PaCarousel` wrapping the same cards (see skeleton above). Card footer takes the action:
+
+```vue
+<div class="pa-grid-3">
+  <PaCard v-for="(svc, i) in services" :key="i" typology="portrait"
+          :title="svc.title" :body="svc.body"
+          :category="svc.category" :category-icon="svc.icon"
+          :image-src="svc.image" image-ratio="3:2">
+    <template #footer><PaButton variant="tertiary" size="sm">Scopri</PaButton></template>
+  </PaCard>
+</div>
+```
+
+### Tabbed content (Dashboard, Landing, Marketing)
+
+```vue
+<PaTabs :tabs="tabs" v-model:active-id="activeTab" label="Sezioni dell'area personale">
+  <template #panel-pratiche>
+    <PaTable :columns="praticheColumns" :rows="praticheRows" />
+    <PaPagination v-model:current-page="currentPage" :total-items="totalItems" />
+  </template>
+  <template #panel-documenti>
+    <div class="pa-grid-3"><PaCard /><!-- … --></div>
+  </template>
+</PaTabs>
+```
+
+### Accordion FAQ / collapsible sections (Event, Marketing, ServiceInfo)
+
+```vue
+<section class="pa-container pa-section">
+  <h2 class="pa-section-title">Programma della giornata</h2>
+  <PaAccordionGroup v-model="openIds" :multiple="true">
+    <PaAccordion id="giorno-1" title="Mattina — Cerimonia ufficiale" icon="clock">
+      <p><strong>10:00</strong> — Alzabandiera in Piazza del Municipio</p>
+    </PaAccordion>
+    <!-- one PaAccordion per entry -->
+  </PaAccordionGroup>
+</section>
+```
+
+### Form panel (Contact, MultiStepForm)
+
+Form fields in a `.pa-grid-2`; full-width fields wrapped in `.pa-field-full-row`; actions in `.pa-form-action-bar`; feedback via `PaBanner` at the top:
+
+```vue
+<form class="pa-panel" @submit.prevent="submitForm">
+  <PaBanner v-if="submitted" variant="success" title="Messaggio inviato" />
+
+  <div class="pa-grid-2">
+    <PaInput v-model="nome" label="Nome e cognome" required />
+    <PaInput v-model="email" type="email" label="Email" required />
+    <PaSelect v-model="argomento" :options="argomentoOptions" label="Argomento" required />
+    <div class="pa-field-full-row">
+      <PaTextarea v-model="messaggio" label="Messaggio" :rows="5" required />
+    </div>
+    <div class="pa-field-full-row">
+      <PaCheckbox v-model="privacy" label="Ho letto e accetto l'informativa privacy" required />
+    </div>
+  </div>
+
+  <div class="pa-form-action-bar">
+    <PaButton variant="ghost">Annulla</PaButton>
+    <PaButton variant="primary" type="submit">Invia messaggio</PaButton>
+  </div>
+</form>
+```
+
+### Multi-step form (MultiStepForm)
+
+`PaStepProgressBar` above the form panel; back/draft/next in a split footer:
+
+```vue
+<div class="pa-container">
+  <h1 class="pa-page-title">Richiesta certificato di residenza</h1>
+  <PaStepProgressBar :steps="steps" orientation="horizontal" label="Avanzamento richiesta" />
+  <form class="pa-panel" @submit.prevent="confirmOpen = true"><!-- pa-grid-2 fields … --></form>
+</div>
+```
+
+### Search hero + results + pagination (SearchList)
+
+Gradient band with the search bar, filters via `PaDrawer`, active filters as a `.pa-tag-cloud` of chips:
+
+```vue
+<div class="pa-section pa-section--gradient pa-section--lg">
+  <div class="pa-container">
+    <h1>Servizi</h1>
+    <div class="pa-narrow">
+      <PaSearchBar v-model:value="searchValue" placeholder="Es. carta d'identità…" />
+    </div>
+  </div>
+</div>
+
+<section class="pa-container pa-section">
+  <PaButton variant="secondary" @click="drawerOpen = true">
+    <template #icon-left><PaIcon name="funnel" size="sm" /></template>
+    Filtri ({{ activeChips.length }})
+  </PaButton>
+  <div class="pa-tag-cloud">
+    <PaChip v-for="label in activeChips" :key="label" variant="dismissible" @close="remove(label)">
+      {{ label }}
+    </PaChip>
+  </div>
+
+  <div class="pa-grid-3"><!-- PaCard results --></div>
+  <PaPagination v-model:current-page="currentPage" :total-items="totalItems" />
+</section>
+```
+
+### Metadata info strip (EventDetail)
+
+```vue
+<div class="pa-info-strip">
+  <div v-for="item in infoStrip" :key="item.label" class="info-cell">
+    <PaIcon :name="item.icon" size="lg" />
+    <div>
+      <p class="pa-eyebrow pa-eyebrow--sm">{{ item.label }}</p>
+      <p>{{ item.value }}</p>
+    </div>
+  </div>
+</div>
+```
+
+### Article with sticky TOC sidebar (ArticleDetail)
+
+```vue
+<div class="pa-layout-sidebar pa-layout-sidebar--sm pa-layout-sidebar--left">
+  <div class="pa-prose">
+    <h2 id="sintesi">In sintesi</h2>
+    <p>…</p>
+    <figure>
+      <PaImage :src="inlineImage" alt="…" ratio="16:9" />
+      <figcaption>…</figcaption>
+    </figure>
+    <blockquote class="pa-blockquote">
+      <p>…</p>
+      <cite>— Sindaco, intervento in Consiglio</cite>
+    </blockquote>
+  </div>
+
+  <aside>
+    <div class="pa-tint-card pa-tint-card--sticky">
+      <p class="pa-eyebrow">In questa pagina</p>
+      <a v-for="s in sections" :key="s.id" :href="`#${s.id}`">{{ s.label }}</a>
+    </div>
+  </aside>
+</div>
+```
+
+### Centered auth card (Login)
+
+```vue
+<main id="main">
+  <div class="login-card pa-narrow pa-narrow--xs">
+    <div class="pa-icon-circle-xl"><PaIcon name="lock-key" size="lg" /></div>
+    <h1>Accedi all'area personale</h1>
+    <div class="pa-stack-xs"><!-- one button per identity provider --></div>
+    <div class="pa-divider pa-divider--text">oppure</div>
+    <!-- credentials form -->
+  </div>
+</main>
+```
+
+## Header/footer data shapes
+
+```ts
+import type {
+  PaHeaderNavItem, PaHeaderLanguage, PaFooterColumn, PaFooterAddress, PaFooterSocial,
+} from '@semplice-studio/pa-design-system'
+
+const mainNav: PaHeaderNavItem[] = [
+  { label: 'Servizi', href: '/servizi' },                      // leaf → plain link
+  { label: 'Amministrazione', children: [                      // branch → mega menu
+    { label: 'Organi di governo', children: [{ label: 'Sindaco', href: '#' }] },
+  ]},
+]
+const languages: PaHeaderLanguage[] = [{ code: 'ita', label: 'ITA' }, { code: 'eng', label: 'ENG' }]
+
+const footerSitemap: PaFooterColumn[] = [
+  { heading: 'Amministrazione', links: [{ label: 'Uffici', href: '#' }] },
+]
+const footerAddress: PaFooterAddress = {
+  title: 'Sede legale',
+  lines: ['Piazza del Municipio, 1 — 00100 Roma', 'P.IVA 00000000000'],
+}
+const footerSocials: PaFooterSocial[] = [{ icon: 'facebook-logo', href: '#', label: 'Facebook' }]
+```
+
+Logged-in header chrome goes through slots: `#user` (avatar chip), `#utility-links` (bare `<a>` strip), `#utility-icons` (bare icon `<button>`s — chrome is applied by the header).
+
+## State wiring cheat-sheet
+
+```ts
+const activeTab = ref('pratiche')          // PaTabs        v-model:active-id
+const openIds = ref<string[]>(['intro'])   // PaAccordionGroup v-model (+ :multiple)
+const currentPage = ref(1)                 // PaPagination  v-model:current-page
+const carouselPage = ref(0)                // PaCarousel    v-model:current-page (0-indexed)
+const drawerOpen = ref(false)              // PaDrawer      v-model:open
+const modalOpen = ref(false)               // PaModal       v-model:open
+const allegato = ref<File | null>(null)    // PaFileUpload  v-model
+```
+
+## Page-level conventions
+
+- `<main id="main">` always — the headers' skip link targets `#main`.
+- Heading discipline: one `<h1>` per page (`.pa-page-title` or PaHero's title); sections use `<h2 class="pa-section-title">`; anchor `id`s on `<h2>` for TOC links.
+- `.pa-eyebrow` as the small uppercase pre-label above section headings.
+- Breadcrumb sits in its own `.pa-container` strip directly under the header.
+- `PaTag` = read-only badge; `PaChip` = interactive filter/selection.
+- `label` props on `PaTabs`/`PaCarousel`/`PaPagination`, `aria-label` on icon-only buttons.
+- Section rhythm comes from `.pa-section`/`--lg` + `.pa-stack-*`; avoid ad-hoc margins between siblings.

package/docs/public-surface.md

@@ -0,0 +1,68 @@
+# Public surface — @semplice-studio/pa-design-system
+
+> One row per export — update after every release. Full prop signatures live in each component's `.d.ts` (shipped in `dist/`); detailed behavioral contracts and deferred-feature notes from v1.x live in this file's git history (pre-2026-06-06).
+
+Every component exports from the barrel **and** from `./components/<Name>`, together with its `*Props` / option types.
+
+Stylesheets: `./tokens.css` (design tokens + bundled Inter/Roboto Mono via `@font-face` — no separate font loading needed), `./layout.css` (`.pa-*` layout utilities; auto-imported by tokens.css), `./style.css` (component styles).
+
+**`anatomy*`** in the API column = the shared form-field prop set: `label`, `helperText`, `error`, `valid`, `required`, `disabled`, `readonly`, `id`, `name` (error message wins over helper).
+
+## Atoms
+
+| Export | Contract | API |
+|---|---|---|
+| `PaButton` | brand button; icon-only square mode needs `aria-label` | props: `variant: primary\|secondary\|tertiary\|accent\|ghost\|error\|success`, `size: sm\|lg`, `disabled`, `type`, `iconOnly` · slots: default, `icon-left`, `icon-right` · emits: `click` |
+| `PaInput` | text field; password toggle; clearable; native attr forwarding | props: `type: text\|email\|tel\|url\|password\|number\|date`, `size: sm\|lg`, `clearable`, anatomy* · v-model: `string` · slots: `icon-prefix`, `icon-suffix` |
+| `PaTextarea` | multiline mirror of PaInput; char counter when `maxlength` set | props: `rows`, anatomy* · v-model: `string` |
+| `PaIcon` | curated Phosphor registry (130 names); decorative unless `title` set | props: `name: PaIconName`, `size: sm\|md\|lg`, `title` |
+| `PaSelect` | native `<select>` with PaInput anatomy | props: `options: PaSelectOption[]` (per-option `disabled`), `size: sm\|lg`, `placeholder`, anatomy* · v-model: `string` |
+| `PaCheckbox` | single checkbox; also the row primitive of PaCheckboxGroup | props: `indeterminate`, `value`, anatomy* · v-model: `boolean` |
+| `PaChip` | pill — dismissible or toggleable | props: `variant: dismissible\|selectable`, `icon`, `disabled` · v-model: `boolean` (selectable) · emits: `close` (dismissible) |
+| `PaTag` | static status badge; non-interactive (use PaChip for that) | props: `variant: default\|info\|alert\|warning\|success\|default-dark`, `icon` |
+| `PaToggle` | on/off switch (`role="switch"`) | props: anatomy*, `value` · v-model: `boolean` |
+| `PaAccordion` | disclosure; group-aware under PaAccordionGroup | props: `title`, `icon`, `defaultOpen`, `id` · v-model: `boolean` · slots: default (body), `title` |
+| `PaFab` | floating action button; positioning is consumer's | props: `icon: PaIconName` (required), `variant: primary\|inverse`, `size: sm\|md`, `extended`, `label`, `ariaLabel` · click via attrs fall-through |
+| `PaImage` | ratio-locked image (cover crop); empty-state placeholder | props: `src`, `alt` (required; `''` = decorative), `ratio: 1:1\|4:3\|16:9\|3:2\|2:3\|3:4\|9:16`, `ratioCustom` |
+| `PaProgressBar` | determinate or indeterminate; presentational only | props: `value: 0–100` (clamped), `label`, `showPercentage`, `indeterminate` |
+| `PaTab` | valid only inside `PaTabs`; renders its panel when active | props: `id` (required), `label`, `icon`, `disabled` · slot: default (panel body) |
+| `PaDrawerInfoRow` | key-value row for drawer bodies | props: `variant: header\|text\|text-multiline\|link\|number\|date` (required), `label`, `value`, `href` (link) · slots: `label`, `value` |
+
+## Composed
+
+| Export | Contract | API |
+|---|---|---|
+| `PaRadioGroup` | single-select radio group | props: `options: PaRadioGroupOption[]` (per-option `disabled`), anatomy* · v-model: `string` |
+| `PaCheckboxGroup` | multi-select; option-array order preserved | props: `options: PaCheckboxGroupOption[]`, anatomy* · v-model: `string[]` |
+| `PaBreadcrumb` | nav trail; auto-truncates beyond `maxItems` | props: `items: PaBreadcrumbItem[]` (`icon?` per item), `maxItems: 3`, `separator: '/'`, `label` · emits: `select({ index, item, event })` — `preventDefault()` for SPA routing |
+| `PaFileUpload` | single-file picker (PaButton + dismissible PaChip); consumer handles upload | props: `accept`, `maxSize` (bytes), `buttonLabel`, `chipLabel: (file) => string`, anatomy* · v-model: `File \| null` · emits: `invalid({ file, reason })` |
+| `PaAccordionGroup` | coordinates PaAccordion children | props: `multiple` · v-model: `string \| null` (single-open) or `string[]` (multiple) · slot: default (PaAccordion children) |
+| `PaImageGrid` | CSS grid of PaImage children; settings flow down via inject | props: `columns: 3`, `ratio`, `gap` · slot: default (PaImage children) |
+| `PaStepProgressBar` | wizard steps; statuses derived from index, per-step override wins | props: `steps: { label, status?: done\|current\|upcoming\|error }[]`, `currentStep`, `orientation: horizontal\|vertical`, `label` · emits: `select({ index, item, status, event })` (done/current/error only) |
+| `PaBanner` | advisory banner; auto `role`/`aria-live` per variant | props: `variant: info\|info-dark\|success\|warning\|error`, `title` (required), `label` · slots: default (body), `action` |
+| `PaTabs` | tab strip; full ARIA + keyboard; array or composition API | props: `tabs: { id, label, icon?, disabled? }[]`, `variant: line\|background`, `label` · v-model: `activeId: string` · slots: `panel-<id>` (array API) or nested `<PaTab>` children |
+| `PaPagination` | numbered strip or items-per-page bar | props: `variant: cursor-number\|items-page`, `totalItems` (required), `pageSizeOptions: [10,25,50,100]`, `disabled`, label props · v-model: `currentPage`, `pageSize` |
+| `PaHero` | page hero (text + PaImage); slot wins over prop | props: `title`, `titleLevel: 1–6`, `subtitle`, `body`, `imageSrc`, `imageAlt`, `imageRatio: 3:2`, `imagePosition: left\|right` · slots: `breadcrumb`, `label`, `title`, `subtitle`, `body`, `cta` |
+| `PaTitleBar` | section title bar; mobile kebab dropdown | props: `title` (required), `titleLevel: 1–6`, `subtitle`, `variant: dark\|light`, `menuItems: { label, onClick?, disabled? }[]`, `menuLabel` · v-model: `menuOpen: boolean` · slot: `actions` |
+| `PaCard` | content card; slot wins over prop | props: `typology: landscape\|portrait\|process`, `variant: light\|dark`, `title`, `titleLevel`, `subtitle`, `body`, `signature`, `date`, `category`, `categoryIcon`, `imageSrc`/`imageAlt`/`imageRatio` · slots: `title`, `subtitle`, `body`, `signature`, `header-leading`, `header-trailing`, `footer` |
+| `PaModal` | teleported dialog; focus trap + scroll lock; Esc/backdrop close | props: `title`, `titleLevel`, `subtitle`, `leadingIcon`, `showClose`, `closeLabel`, `size: sm\|md\|lg` · v-model: `open: boolean` · slots: default (body), `footer` |
+| `PaTable` | native table; opt-in row selection | props: `columns: { key, label, align?, width? }[]`, `rows`, `label`, `selectable`, `rowId: (row, i) => string`, `selectionLabel` · v-model: `selectedRowIds: string[]` · slots: `cell-<key>` (scoped: `{ row, value, index }`) |
+| `PaCarousel` | paginated slide strip over arbitrary children; scroll-snap; page-indexed | props: `itemsPerPage: 1\|2\|3`, `showChevrons`, `showDots`, label props · v-model: `currentPage: number` (0-indexed) · slot: default (slides) |
+| `PaSearchBar` | search input + button; optional combobox dropdown (consumer pre-filters) | props: `placeholder`, `debounceMs: 0`, `options: { value, disabled? }[]`, `searchLabel`, `clearLabel`, `label`, `helperText`, `disabled` · v-model: `value: string` · emits: `search(value)`, `clear`, `select(option)` |
+| `PaDrawer` | teleported slide-out panel; focus trap | props: `title`, `titleLevel`, `showClose`, `closeLabel`, `position: right\|left\|top\|bottom`, `size: sm\|md\|lg` · v-model: `open: boolean` · slots: default (body), `footer` (sticky CTA bar) |
+| `PaFooter` | page footer: back-to-top + sitemap + contact + privacy bands, each omitted when its data is absent | props: `backToTop: boolean \| { label?, ariaLabel? }`, `sitemap: PaFooterColumn[]`, `address: { title?, lines }`, `socials: { icon, href, label }[]`, `copyright`, `showRepublicEmblem` · slots: `logo`, `sitemap`, `address`, `socials`, `contact-extra`, `privacy-logo`, `copyright` · emits: `back-to-top` (preventable) |
+| `PaHeaderMobile` | mobile header bar + full-screen drill-down menu | props: `loggedIn`, `primaryNav`/`secondaryNav: PaHeaderNavItem[]`, `languages: PaHeaderLanguage[]`, `currentLanguage`, `skipLink`, `teleportTarget`, copy props · v-model: `menuOpen: boolean` · slots: `logo`, `actions`, `user` · emits: `navigate`, `language-change` (both preventable), `search-click`, `user-click` |
+| `PaHeaderDesktop` | desktop header: utility row + PaSearchBar + nav with 3-column mega menu | props: `loggedIn`, `mainNav: PaHeaderNavItem[]`, `languages`, `currentLanguage`, `currentHref`, `searchEnabled` + search props, `loginLabel`/`loginHref`, `skipLink`, copy props · v-model: `menuOpen: string \| null` · slots: `utility-links`, `utility-icons`, `language`, `user`, `search`, `mega-column-0/1/2` (scoped) · emits: `navigate` (preventable), `language-change`, `search` |
+| `PaDatePicker` | single-day picker (v-calendar); popover or inline | props: `display: popover\|inline`, `placeholder`, `min`/`max: Date`, `disabledDates: (d) => boolean`, anatomy* · v-model: `Date \| null` · slot: `suffix` |
+| `PaRangePicker` | day-range picker (v-calendar); two-click commit, auto start ≤ end | props: same as PaDatePicker · v-model: `PaRangePickerValue ({ start, end }) \| null` · slot: `suffix` |
+| `PaMonthPicker` | month-grid picker; value = 1st of month | props: same chrome, `disabledMonths: (d) => boolean` · v-model: `Date \| null` · slot: `suffix` |
+| `PaYearPicker` | 12-year-grid picker; value = Jan 1 | props: same chrome, `disabledYears: (d) => boolean` · v-model: `Date \| null` · slot: `suffix` |
+| `PaTimePicker` | HH:MM spinner with wrap + step-skip of disabled times | props: `display`, `placeholder`, `min`/`max: PaTimePickerValue`, `disabledTimes: (t) => boolean`, anatomy* · v-model: `PaTimePickerValue ({ hours, minutes }) \| null` · slot: `suffix` |
+
+## Cross-cutting conventions
+
+- **Form anatomy is shared** (`anatomy*` above): every form-ish component mirrors PaInput's field chrome; the error message wins over the helper text.
+- **Date/time pickers**: Italian locale hardcoded; all values normalized to **local** midnight (never UTC); with `name` set, a hidden input serializes for native form posts (`yyyy-mm-dd`, `yyyy-mm-dd/yyyy-mm-dd`, `yyyy-mm`, `yyyy`, `HH:mm`).
+- **Italian default labels throughout** (`'Chiudi'`, `'Ricerca'`, `'Torna su'`, …) — all overridable via props for other locales.
+- **Responsive collapse uses container queries**, not viewport media queries — components reflow inside narrow sidebars on wide screens.
+- **Router integration**: nav-emitting components (`PaBreadcrumb`, headers, footer) emit preventable payloads — call `preventDefault()` and route with your SPA router.