content: enhance README

[Fupete]

fix: #1072

[github-actions]

⚡ Lighthouse report for the home page 🏠

Category	Score
🟠 Performance	61
🟢 Accessibility	100
🟢 Best practices	100
🟢 SEO	100

See the full report...

Other pages

• /progetto/ 🟠 81 🟢 100 🟢 100 🟢 100
• /norme-e-riferimenti/linee-guida-di-design/ 🟠 79 🟢 100 🟢 100 🟢 100
• /design-system/componenti/ 🟠 80 🟢 100 🟢 100 🟢 100

[bfabio]

Uhm, we should IMO refactor the scripts a little bit, so that the prerequisites of the commands are explicit and self-documenting using pre-scripts.

That way the scripts section would also be leaner, more maintainable and more readable. I'd also rename prepare-* to avoid confusion, as prepare has a special meaning for npm

WDYT about:

   "scripts": {
     "copy-assets": "cp -r node_modules/bootstrap-italia/dist/svg/ static/ && cp -r node_modules/bootstrap-italia/dist/fonts static/",
     "...": "...",
     "prestart": "npm run copy-assets"
     "start": "gatsby develop",
     "...": "...",
     "prebuild": "npm run copy-assets"
     "build": "gatsby build --prefix-paths"

Also, I'd rename prepare-content (and the supporting scripts it runs under scripts/) to something more specific and self-documenting. AFAIR that script syncs the local examples with the latest (or tagged?) Bootstrap Italia components and it's supposed to run manually when a new version is out, is that right.

Something like sync-bootstrap-italia-examples or sync-design-system-examples/update-design-system-examples.

Bonus: it would make sense to run it from here automatically: https://github.com/italia/designers.italia.it/blob/main/.github/workflows/bsi-update.yml

[Fupete]

Uhm, we should IMO refactor the scripts a little bit, so that the prerequisites of the commands are explicit and self-documenting using pre-scripts.

That way the scripts section would also be leaner, more maintainable and more readable. I'd also rename prepare-* to avoid confusion, as prepare has a special meaning for npm

WDYT about:

   "scripts": {
     "copy-assets": "cp -r node_modules/bootstrap-italia/dist/svg/ static/ && cp -r node_modules/bootstrap-italia/dist/fonts static/",
     "...": "...",
     "prestart": "npm run copy-assets"
     "start": "gatsby develop",
     "...": "...",
     "prebuild": "npm run copy-assets"
     "build": "gatsby build --prefix-paths"

Also, I'd rename prepare-content (and the supporting scripts it runs under scripts/) to something more specific and self-documenting. AFAIR that script syncs the local examples with the latest (or tagged?) Bootstrap Italia components and it's supposed to run manually when a new version is out, is that right.

Something like sync-bootstrap-italia-examples or sync-design-system-examples/update-design-system-examples.

All cool to me. If these things are feasible in a short period of time let's proceed directly on this branch. If not, I would prefer to take an intermediate step by first updating the README to the state of the art, then later opening a PR dedicated to evolutions. WDYT?

Bonus: it would make sense to run it from here automatically: https://github.com/italia/designers.italia.it/blob/main/.github/workflows/bsi-update.yml

Not really. It is one thing to update BSI of the site. That can happen automatically, although at the moment PR for some reason actually still doesn't go through and will have to be fixed.
Other would be to auto-update the component examples in the design system documentation instead, copying from the BSI API, which impacts the need for a new release of the Design system documentation. For now I prefer to do by hand. Then later perhaps we can evaluate automatisms.

[bfabio]

Also, I'd rename prepare-content (and the supporting scripts it runs under scripts/) to something more specific and self-documenting. AFAIR that script syncs the local examples with the latest (or tagged?) Bootstrap Italia components and it's supposed to run manually when a new version is out, is that right.
Something like sync-bootstrap-italia-examples or sync-design-system-examples/update-design-system-examples.

All cool to me. If these things are feasible in a short period of time let's proceed directly on this branch. If not, I would prefer to take an intermediate step by first updating the README to the state of the art, then later opening a PR dedicated to evolutions. WDYT?

Sounds good, the renaming part is really simple and can be done quickly in this PR.

Bonus: it would make sense to run it from here automatically: https://github.com/italia/designers.italia.it/blob/main/.github/workflows/bsi-update.yml

Not really. It is one thing to update BSI of the site. That can happen automatically, although at the moment PR for some reason actually still doesn't go through and will have to be fixed. Other would be to auto-update the component examples in the design system documentation instead, copying from the BSI API, which impacts the need for a new release of the Design system documentation. For now I prefer to do by hand. Then later perhaps we can evaluate automatisms.

Uhm, so there is no link between the locally installed Bootstrap Italia and the examples generation. This threw me off: https://github.com/italia/designers.italia.it/blob/main/scripts/generate-examples.js#L6 and I think it's wrong, IIUC.