18
Linee guida di sviluppo
Nucleo comuneDevelopment Guidelines
Lo stack lo fissano le Linee guida aziendali per i nuovi progetti. Qui si dice solo dove vive il design system dentro un progetto.
Rapporto fra i due documentiLe linee guida dicono con cosa si costruisce, MaeDesign come deve apparire. Dove si sovrappongono — tabella dati, icone, validazione — vince lo stack.
A chi serveNon c'è più un framework di frontend aziendale: al suo posto stanno questo documento, lo stack e le skill. Chi sviluppa lavora con un code assistant, quindi le regole devono poter essere citate per numero e finire nel CLAUDE.md del progetto. Un estratto in Markdown di tutte le regole, pensato per essere dato in pasto all'assistente, è il passo successivo: questo documento resta quello che si legge e si presenta.
Dove vive il design system
Lo stack prescrive un frontend feature-first, con una shared/ per l'adapter JSON:API e il design system. MaeDesign occupa quella cartella.
web/src/
├── shared/
│ ├── design/ MaeDesign vive qui
│ │ ├── theme.ts createTheme: raggi, tipografia, predefiniti dei componenti
│ │ ├── base.css i ruoli: --bg, --surface, --ink-*, --line-*, --elev-*
│ │ ├── palette-nome.css una per palette: dominante, co-primario, semantici
│ │ ├── components/ quello che Mantine non ha: EmptyState, PageHeader…
│ │ ├── useIsMobile.ts la soglia del telefono, in un posto solo
│ │ └── useMaeTable.tsx il preset di mantine-datatable (§11)
│ └── api/ adapter JSON:API
├── features/
│ └── dominio/{api,components,hooks,pages}
└── app/
└── shell.tsx AppShell: la shell della sezione 13
18.1Un progetto consuma il design system, non lo copia. Le differenze stanno nel foglio di palette e nel tema.nucleo
18.2Nessun componente di features/ dichiara un colore, un raggio, un'ombra o un corpo di testo: cita ruoli. Un esadecimale lì si respinge in revisione.nucleo
18.3Il tema Mantine è uno e sta in theme.ts: raggi, tipografia, focusRing, defaultProps.struttura
18.4I colori passano da CSS variables, non dal tema: il tema porta forma e tipografia, il foglio di palette il colore. Così si sostituisce a runtime.struttura
18.5Si aggiunge qualcosa solo quando Mantine non ce l'ha. Oggi cinque: tre componenti — empty state (14), intestazione di pagina (6), footer di salvataggio (7) — e due hook, useMaeTable (11) e useIsMobile (15).struttura
18.6Nessun testo scritto nel codice. Con i18next le regole di scrittura della 7 si applicano ai file di traduzione, e il glossario è il catalogo delle chiavi.nucleo
18.7Cosa si vede e cosa è disattivato lo decide CASL. I quattro casi della tabella dei permessi (7) vanno distinti nel codice, non collassati su un can().nucleo
18.8Le app native sono la stessa applicazione: Capacitor incapsula la SPA, non c'è un design system mobile separato.struttura
Il tema, in concreto
// shared/design/theme.ts — forma e tipografia. Nessun colore: quello sta nei CSS.
export const maeTheme = createTheme({
fontFamily: 'IBM Plex Sans, system-ui, sans-serif',
headings: { fontFamily: 'IBM Plex Sans, system-ui, sans-serif', fontWeight: '600' },
fontSizes: { xs: '13px', sm: '14px', md: '15px', lg: '16px', xl: '20px' },
radius: { xs: '4px', sm: '6px', md: '10px', lg: '14px', xl: '14px' },
defaultRadius: 'sm', // il predefinito di Mantine 9 è 'md': la sostituzione è dichiarata
focusRing: 'auto', // mai 'never' (7.12)
components: {
Alert: Alert.extend({ defaultProps: { variant: 'outline', radius: 'md' } }),
Badge: Badge.extend({ defaultProps: { variant: 'outline' } }),
Button: Button.extend({ defaultProps: { radius: 'sm' } }),
},
});
StrutturaCon Alert a tratto per difetto, variant="light" — in Mantine 9 un fondo pieno — diventa una scelta esplicita che si vede in revisione.
Verifiche automatiche
Le linee guida aziendali dicono che le convenzioni si fissano con un test, non con un paragrafo. Qui il paragrafo è questo documento.
| Regola | Come si verifica | Esito |
Nessun esadecimale in features/ | Regola ESLint su valori di colore letterali nei file di stile e nelle prop style | Errore. npm run lint a zero warning è già un gate dello stack |
| Nessun testo scritto nel codice | Regola ESLint sulle stringhe letterali nel JSX | Errore, con eccezione dichiarata per i simboli |
| Contrasto della palette | Test unitario che calcola il rapporto di ogni coppia dichiarata nel foglio | Rosso sotto 4,5:1 per il testo, 3:1 per gli oggetti grafici |
| Pavimento tipografico | Test sui token: nessuna dimensione sotto 13px oltre le due deroghe della 4.2 bis | Rosso, con l'elenco delle eccezioni ammesse nel test stesso |
| Empty state obbligatorio | Revisione: ogni tabella dichiara renderEmptyRowsFallback | Manuale, in attesa di una regola che lo colga |
Da fareNessuna esiste oggi: due regole ESLint e due test unitari da scrivere. Finché non esistono, questo documento è un paragrafo che si dimentica.
Nel CLAUDE.md del progetto
La parte di interfaccia del CLAUDE.md si scrive una volta e dice poco:
## Interfaccia
Il design system è MaeDesign v3, in `shared/design/`. Palette: `palette-celeste.css`.
- Mai un colore, un raggio, un'ombra o un corpo di testo scritti in `features/`: si citano i ruoli.
- Tabelle: `useMaeTable`, non `useMantineReactTable` configurato a mano.
- Icone: `@tabler/icons-react`. Mai un'icona senza parola fuori dalle azioni di riga.
- Stati vuoti: `<EmptyState variant="…" />`, quattro varianti, mai "Nessun risultato".
- Deroghe a MaeDesign: come le variazioni di stack, autorizzate e scritte in `docs/DECISIONI.md`.
Il perchéCorrispondenze componente per componente in Disposizione, cap. 8. Lo stack completo nelle Linee guida aziendali: qui non si duplica.