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

package/README.md

@@ -1,166 +1,123 @@
-# Coding-Agent Project Template
+# @semplice-studio/pa-design-system
 
-A boilerplate that captures the Sapra.ai development methodology — a **Plan first, Develop second** workflow optimized for working with a coding agent like Claude Code.
+Vue 3 design system for Italian **Pubblica Amministrazione (PA)** web portals — accessible, brand-consistent components and design tokens, by [Semplice](https://semplice.is).
 
-This template doesn't ship application code. It ships the **scaffolding the agent needs** to make good decisions in your project: a structured `CLAUDE.md`, a `docs/` knowledge base, and a set of skills (`/init-prd`, `/import-design-system`, `/data-model`, `/user-story`, `/ui-composer`, `/figma-component`) that drive the project from empty repo to shipped feature.
+- **41 components** (15 atoms + 26 composed) — forms, navigation, overlays, data display, date/time pickers
+- **Design tokens as CSS custom properties**, with Inter + Roboto Mono bundled via `@font-face`
+- **Accessibility-first**: WAI-ARIA patterns, keyboard navigation, focus management — built toward Italian PA requirements (AgID / Legge Stanca)
+- **ESM-only**, tree-shakeable, typed (`.d.ts` for every component)
+- Italian default labels everywhere, overridable via props for other locales
 
-## Philosophy
+> ⚠️ **Pre-1.0**: minor versions may contain breaking changes until `v1.0.0`.
 
-- **Knowledge as code.** Everything the agent needs to know lives in version-controlled markdown — no tribal knowledge, no Slack archeology.
-- **One conversation per phase.** Each skill is a guided Q&A that produces one durable artifact (PRD, design system, data model, user story).
-- **Plan first, develop second.** No code is written before a plan is confirmed. Stories are drafted before they're built. Components are mapped before they're composed.
-- **Per-step approval.** The agent never batch-implements. Every user story gets its own approval gate.
+## Requirements
 
-## The flow
+- Vue **≥ 3.4**
+- Node **≥ 20** (build tooling)
 
-There are two flavors depending on what you're building. Pick one bootstrap skill at step 2 — the rest is identical.
+## Installation
 
-### Product / app project
-
-```
-1. Clone this template       →  empty repo with .claude/ + docs/ scaffolding
-2. /init-prd                 →  dialog → docs/prd.md + populated CLAUDE.md
-3. /import-design-system     →  Figma → docs/frontend/design-system.md + tokens
-4. /data-model               →  dialog → docs/data-model.md + schema sketch
-5. /user-story <topic>       →  Q&A → docs/user-stories/user-stories-vX.X.md
-6. /user-story implement vX.X →  loop: plan → approve → implement → tick AC
-7. git commit                →  one bundled commit per story
-```
-
-### Library / npm package project (e.g. a Vue design system)
-
-```
-1. Clone this template       →  empty repo with .claude/ + docs/ scaffolding
-2. /init-library             →  dialog → docs/prd.md (library spec) + CLAUDE.md
-                                + optional package.json + tsconfig + build config
-3. /import-design-system     →  Figma → docs/frontend/design-system.md + tokens
-4. (skip /data-model — libraries have no data model)
-5. /user-story <component>   →  Q&A → docs/user-stories/user-stories-vX.X.md
-6. /user-story implement vX.X →  loop: plan → approve → /figma-component → tick AC
-7. git commit                →  one bundled commit per story (or per component)
+```bash
+pnpm add @semplice-studio/pa-design-system
+# or: npm install / yarn add
 ```
 
-The two paths are mutually exclusive — you pick `/init-prd` or `/init-library` once per project, not both.
+`@phosphor-icons/vue` and `v-calendar` are installed automatically as dependencies; `vue` is a peer.
 
-## How this maps to software development phases
+## Quickstart — Nuxt 3/4
 
-The template isn't a novel methodology — it's a classic software development lifecycle, reorganized so that **every phase produces an agent-readable artifact** and **every artifact accumulates into a living knowledge base**.
-
-The flow has two macro-phases:
-
-- **Setup** — one-shot at project start. Produces the blueprints.
-- **Iteration** — repeated forever, one user story at a time. Produces the software.
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  css: [
+    '@semplice-studio/pa-design-system/tokens.css',
+    '@semplice-studio/pa-design-system/style.css',
+  ],
+})
+```
 
-A third theme runs across both: **knowledge accumulation**. Every skill writes back to `docs/`, so every future agent session starts with more context, not less.
+```vue
+<script setup lang="ts">
+import { PaButton, PaInput } from '@semplice-studio/pa-design-system'
+</script>
 
-### Setup phase (one-shot)
+<template>
+  <PaInput v-model="name" label="Nome" />
+  <PaButton @click="submit">Invia</PaButton>
+</template>
+```
 
-| SDLC phase | Skill | Artifact | Inputs the next phase will consume |
-|---|---|---|---|
-| Requirements / discovery | `/init-prd` (product) or `/init-library` (npm package) | `docs/prd.md` + populated `CLAUDE.md` | Personas/package surface, scope, stack, constraints |
-| UX / visual design | `/import-design-system` | `docs/frontend/design-system.md` + token files + Figma→component recognition rules | Components available, token names, icon registry |
-| System / data design | `/data-model` | `docs/data-model.md` + ORM schema sketch | Entities, relationships, indexes, RLS policies *(skip for library projects)* |
+## Quickstart — plain Vue + Vite
 
-After setup: the project has a complete blueprint. No production code yet — every downstream decision will be anchored to these artifacts.
+```ts
+// main.ts
+import '@semplice-studio/pa-design-system/tokens.css'
+import '@semplice-studio/pa-design-system/style.css'
+```
 
-### Iteration phase (repeated per release)
+Then import components where you use them — no plugin, no global registration.
 
-| SDLC phase | Skill | Artifact | Notes |
-|---|---|---|---|
-| Sprint planning | `/user-story <topic>` | `docs/user-stories/user-stories-vX.X.md` | One file per release. Stories scoped, AC testable, files listed. |
-| Implementation | `/user-story implement vX.X` | Source code + ticked AC | Per-step approval. Calls `/ui-composer` and `/figma-component` as sub-skills when needed. |
-| Component design (sub-skill) | `/figma-component <Name> <figma-url>` | Component file + design-system.md update (status 🟡 → ✅) | Only when a story needs a new atom. |
-| Page composition (sub-skill) | `/ui-composer` | Page file with mock data, AC checklist | Only when a story scaffolds a page from existing atoms. |
-| Review / merge | (manual) | git commit per story | One bundled commit per story; commit message follows `feat(area): <summary> (US-NN)`. |
+## Imports
 
-After each iteration: the codebase grows and the docs grow with it. The next agent session has more context than the previous one — never less.
+```ts
+// barrel — tree-shaken by your bundler
+import { PaButton, PaModal } from '@semplice-studio/pa-design-system'
 
-### Cross-cutting — continuous documentation
+// or per-component subpath
+import { PaButton } from '@semplice-studio/pa-design-system/components/PaButton'
+```
 
-Nothing lives in tribal knowledge. Every skill writes to `docs/`:
+Every component also exports its prop/option types (`PaButtonProps`, `PaSelectOption`, …).
 
-- `/figma-component` updates `docs/frontend/design-system.md` (component status, prop tables, recognition rules)
-- `/user-story implement` ticks acceptance criteria (✅) in the story file and proposes commits
-- New conventions discovered during implementation get appended to the relevant `docs/tech/*.md`
-- `/data-model` is re-runnable when entities change — diffs against the existing model
+## Stylesheets
 
-This is what makes the methodology agent-ready: the project state lives in markdown, not in anyone's head.
+| Entry | Contents |
+|---|---|
+| `tokens.css` | Design tokens (`--pa-color-*`, `--pa-space-*`, `--pa-font-*`, …) + bundled Inter / Roboto Mono `@font-face` — no separate font loading needed. Auto-imports `layout.css`. |
+| `layout.css` | `.pa-*` layout/composition utilities (also importable standalone) |
+| `style.css` | Compiled component styles |
 
-### Typical use case — bootstrapping a Vue design system as an npm package
+## Theming
 
-A concrete walkthrough mapping each step to its SDLC phase:
+All component styling resolves through CSS custom properties — override them at the consumer level, no build-time config:
 
-**Day 1 morning — Requirements**
+```css
+:root {
+  --pa-color-primary: #0a5fad;
+}
 ```
-git clone <template> dx-design-system && cd dx-design-system && claude
-> /init-library
-```
-The agent Q&As through 18 questions (package name, target framework, build tool, peer deps, distribution shape). ~30 min later: `docs/prd.md` is filled with the library spec, `CLAUDE.md` is populated, optional `package.json` + `tsconfig.json` + build config are scaffolded. *Phase: Requirements engineering.*
 
-**Day 1 afternoon — Visual design**
-```
-> /import-design-system
-```
-The agent extracts color/typography/spacing/radius tokens from Figma, enumerates atoms and composed components, builds the icon registry. Output: `docs/frontend/design-system.md` (every component marked 🟡 designed, awaiting implementation), `src/tokens/*.css`, Figma→component recognition rules seeded. *Phase: UX/visual design.*
+## Component reference & agent docs
 
-**(Skip `/data-model` — libraries have no data model.)**
+These docs ship **inside the package** (`node_modules/@semplice-studio/pa-design-system/docs/`), version-locked to the installed release — point your coding agent at them:
 
-**Day 2 morning — Sprint planning**
-```
-> /user-story tokens wiring + 5 base atoms (Button, Input, Badge, Tag, Icon) + Histoire setup
-```
-The agent Q&As scope, AC, file paths, dependencies. Output: `docs/user-stories/user-stories-v1.1.md` with ~6 user stories (US-01 → US-06), each with concrete AC and file paths. *Phase: Sprint planning.*
+- [`docs/public-surface.md`](docs/public-surface.md) — export table: every component with its props/v-model/slots/emits summary
+- [`docs/page-composition-examples.md`](docs/page-composition-examples.md) — page skeleton + section patterns distilled from the reference templates
+- [`docs/layouts.md`](docs/layouts.md) — the `.pa-*` layout utility classes
+- [`docs/design-system.md`](docs/design-system.md) — design tokens + component registry
 
-**Day 2-3 — Implementation**
-```
-> /user-story implement v1.1
-```
-For each US-NN: agent proposes a plan → user approves → agent calls `/figma-component UiButton <figma-url>` as a sub-skill → component generated → `docs/frontend/design-system.md` updated (status 🟡 → ✅) → AC ticked → commit suggested (`feat(button): add UiButton with primary/outline/ghost variants (US-01)`). Loop continues for each story. *Phase: Implementation, with continuous documentation woven in.*
+For live examples, run the Histoire playground (see Development).
 
-**Day 4 — Next iteration**
-```
-> /user-story Composed components: Card, Header, Sidebar
-```
-The agent reads `CLAUDE.md`, `docs/prd.md`, `docs/frontend/design-system.md` (now with 5 ✅ atoms it can compose with), and the previous user-stories file as structural reference. Phase B repeats — but the knowledge base is bigger and the agent's plans are sharper. *Phase: next iteration of sprint planning + implementation.*
+Conventions that apply across the library:
 
-The compounding effect is the point: by Day 30, when you onboard a teammate (or a fresh agent session), they don't ask "where do I start?" — they read `CLAUDE.md`, follow the references, and have the project's full context in 15 minutes.
+- **Shared form anatomy**: form components mirror `PaInput`'s `label` / `helperText` / `error` / `valid` / `required` / `disabled` / `readonly` set
+- **Date/time pickers**: values normalized to *local* midnight (never UTC); with `name` set, a hidden input serializes for native form posts
+- **Responsive components use container queries** — they reflow inside narrow sidebars regardless of viewport
+- **SPA routing**: nav components (`PaBreadcrumb`, headers, footer) emit preventable payloads — call `preventDefault()` and route with your router
 
-## What's in the box
+## Development
 
+```bash
+pnpm install
+pnpm dev          # Histoire playground
+pnpm test         # Vitest (watch)
+pnpm build        # library build + type emit
+pnpm typecheck
+pnpm lint
 ```
-template/
-├── AUDIT.md                  ← what's reusable methodology vs Sapra-specific
-├── CLAUDE.md                 ← skeleton with {{TODO}} slots filled by skills
-├── .claude/skills/
-│   ├── init-prd/             ← NEW: bootstrap a product/app project
-│   ├── init-library/         ← NEW: bootstrap a library/npm package project
-│   ├── import-design-system/ ← NEW: Figma → design-system.md + tokens
-│   ├── data-model/           ← NEW: entities + relationships → data-model.md
-│   ├── user-story/           ← LIFTED from Sapra (deparametrized)
-│   ├── ui-composer/          ← LIFTED from Sapra (deparametrized)
-│   └── figma-component/      ← LIFTED from Sapra (deparametrized, now a skill)
-└── docs/
-    ├── workflow.md           ← Plan-first/Develop-second workflow rules
-    ├── prd.md                ← empty template, filled by /init-prd
-    ├── data-model.md         ← empty template, filled by /data-model
-    ├── frontend/
-    │   └── design-system.md  ← empty template, filled by /import-design-system
-    └── user-stories/         ← created per release by /user-story
-```
-
-## How to use
-
-1. Copy `template/` contents to a fresh repo (the `template/` folder itself is for reference inside Sapra)
-2. Open it in Claude Code — the agent reads `CLAUDE.md` on session start
-3. Decide: is this a **product** or a **library**?
-   - Product/app → run `/init-prd`. Q&A through tech stack, product surface, constraints
-   - Library (npm package, design system, SDK) → run `/init-library`. Q&A through package surface, peer deps, build, distribution
-4. Run `/import-design-system` once your designer has a Figma file ready
-5. Run `/data-model` to lock down entities before any backend work — **skip for library projects**
-6. From there: `/user-story` per feature/component, then `implement vX.X` per release
 
-## Stack-agnostic — but with framework hooks
+Releases use [changesets](https://github.com/changesets/changesets): `pnpm changeset` → `pnpm changeset version` → commit → `pnpm release` → `git push --follow-tags`. Published publicly on npmjs.com (`publishConfig.access: public`); publishing requires npm 2FA.
 
-The methodology is stack-agnostic. The `/ui-composer` and `/figma-component` skills, however, need framework-specific references (which Vue patterns? React? Svelte?). They read `CLAUDE.md` to discover the stack chosen by `/init-prd`, then look up the right reference under `.claude/skills/<skill>/references/frameworks/`. v0 of this template ships Vue/Nuxt as the only framework reference (lifted from Sapra) — adding React/Next is a matter of dropping a new file in `references/frameworks/`.
+## License
 
-See `AUDIT.md` for the full breakdown of what was reusable, what was project-specific, and what needed generalization.
+[EUPL-1.2](LICENSE) © Semplice

package/dist/components/PaDatePicker/PaDatePicker.vue2.js

@@ -1,6 +1,6 @@
 import { defineComponent as G, useModel as H, ref as M, computed as n, watch as J, onBeforeUnmount as Q, openBlock as u, createElementBlock as c, normalizeClass as p, createTextVNode as X, toDisplayString as C, createCommentVNode as v, withKeys as S, withModifiers as q, createElementVNode as g, renderSlot as Z, createVNode as y, withDirectives as ee, unref as ae, withCtx as L, vShow as te, mergeModels as ie } from "vue";
 import { DatePicker as ne } from "v-calendar";
-import "v-calendar/style.css";
+/* empty css                                                                                                                                  */
 import E from "../PaIcon/PaIcon.vue.js";
 const re = ["for"], le = {
   key: 0,

package/dist/components/PaRangePicker/PaRangePicker.vue2.js

@@ -1,6 +1,6 @@
 import { defineComponent as ne, useModel as re, ref as y, computed as o, watch as le, onBeforeUnmount as ie, openBlock as f, createElementBlock as m, normalizeClass as D, createTextVNode as oe, toDisplayString as F, createCommentVNode as k, withKeys as V, withModifiers as _, createElementVNode as w, renderSlot as de, createVNode as M, withDirectives as se, unref as ue, withCtx as W, vShow as ce, mergeModels as ve } from "vue";
 import { DatePicker as ge } from "v-calendar";
-import "v-calendar/style.css";
+/* empty css                                                                                                                                  */
 import B from "../PaIcon/PaIcon.vue.js";
 const fe = ["for"], me = {
   key: 0,