[IOAPPFD0-190] Update assets docs with How to add a new icon and How to add a new pictogram pages

README.md

@@ -92,14 +92,20 @@ Essential core visual attributes of the design language. It includes:
 ## Foundation
 Essential atomic components:
 * [**Typography**](./src/components/typography/)
+  * [📖 Docs](./src/components/typography/README.md) · [Handling font files →](./src/components/typography/README.md#handling-font-files)
 * **Layout**
   * [ContentWrapper](./src/components/contentWrapper/)
   * [Spacer](./src/components/spacer/) (`VSpacer`,`HSpacing`)
   * [Divider](./src/components/divider/)
-* [**Icons**](./src/components/icons/): [📖 Relative docs →](./src/components/icons/)
-* [**Pictograms**](./src/components/pictograms/): [📖 Relative docs →](./src/components/pictograms/)
+* [**Icons**](./src/components/icons/)
+  * Assets with an intended size between `12px` and `56px`
+  * [📖 Docs](./src/components/icons/README.md) · [Add a new icon →](./src/components/icons/#add-a-new-icon)
+* [**Pictograms**](./src/components/pictograms/)
+  * Assets with an intended size greather than `56px`
+  * [📖 Docs](./src/components/pictograms/README.md) · [Add a new pictogram →](./src/components/pictograms/README.md#add-a-new-pictogram)
 * **Logos**
-  * [Payment Logos](./src/components/logos/): [📖 Relative docs →](./src/components/logos/)
+  * [Payment Logos](./src/components/logos/)
+    * [📖 Docs](./src/components/logos/)
   * [Avatar](./src/components/avatar/)
 * **Loaders**
   * [LoadingSpinner](./src/components/loadingSpinner/)

src/components/icons/README.md

@@ -4,33 +4,91 @@ There are different sets:
 * **Navigation**: Icons used in the main Tab bar
 * **Biometric**: Icons used for the biometric identification
 * **Categories**: Icons used for the different sectors available in the Carta Giovani Nazionale
-* **Product**: PagoPA products' icons 
-
-## Prefixes
-- **General**: `Icon…`
-- **Navigation**: `IconNav…`
-- **Biometric**: `IconBiometric…`
-- **Categories**: `IconCateg…`
-- **Product**: `IconProduct…`
+* **Product**: PagoPA products' icons
+* **System**: OS-specific icons (iOS/Android)
 
 ## Add a new icon
-First of all, follow the instructions stated in the main README (`Vector graphics` section).
 
-If you want to add a new icon in the `General` set, open the `Icon.tsx` file and import the React component:
-```jsx
-[…]
-import IconSpid from "./svg/IconSpid";
-[…]
-```
+### Prerequisites
+
+In your user interface design app (Figma/Sketch) export your SVG with `1×` preset. The name usually consists of a specific prefix followed by the associated key:
+  - **General**: `Icon…`
+  - **Navigation**: `IconNav…`
+  - **Biometric**: `IconBiometric…`
+  - **Categories**: `IconCateg…`
+  - **Product**: `IconProduct…`
+  - **System**: `IconSystem…`
+
+> [!important]
+> The icon must be contained within a `24×24` frame.
+
+> [!tip]
+> If you want to add a new `Wallet` icon to be used in the main tab bar, your icon will have a `IconNavWallet` filename. If it doesn't belong to a specific set, you just put the name after the prefix `Icon…`, so `IconWallet`
+
+> [!caution]
+> This filename will be the same as the React component, so make sure you don't already have a component with that filename
+
+### Create the corresponding React component
+
+#### Using `generateNewIcons.js`
+1. Move the exported file to the `icons/svg/originals` folder
+2. In your terminal, in the same folder, run the command: `node generateNewIcons.js`
+3. The script will process `timestamp.txt`, generate the new React components (with `*.tsx` extension) following exactly the steps listed in the manual process (see below), and process **only the files added after this timestamp value**
+4. If the `generateNewIcons` script accidentally overwrites older React components, remember to discard the changes before committing
+
+> [!caution] 
+> If your icon **is not** monochromatic, you should use the manual process because the script doesn't support this specific case yet
+
+#### Manual process (alternative)
+
+1. Move the exported file to the `icons/svg/originals` folder
+2. In your original SVG file, delete `width` and `height` attributes and leave the original `viewBox` attribute. You could easily process the image using online editors like [SVGOmg](https://jakearchibald.github.io/svgomg/) (enable `Prefer viewBox to width/height`)
+3. In the `icons/svg` folder, create a new React component (with a `.tsx` extension) of the same name
+4. Copy all the `<path>` elements into the new React component and replace the original `<path>` with the element `<Path>` (capital P) from the `react-native-svg` package. Replace all the harcoded fill values with the generic `currentColor` value, so that the icon inherits the color from the parent `Svg` container
+
+5. Add the dynamic size and colour (if required), replacing the hardcoded values with the corresponding props. The final result should be similar to the following:
+    ```tsx
+    import { Svg, Path } from "react-native-svg";
+    // [...]
+
+    const IconSpid = ({ size, style }: SVGIconProps) => (
+      <Svg width={size} height={size} viewBox="0 0 24 24" style={style}>
+        <Path
+          d="M13.615 …"
+          fill="currentColor"
+        />
+      </Svg>
+    );
+    ```
+6. Repeat the previous steps for each icon
+7. Once you have finished processing all the new icons, run `node generateNewTimestamp` to avoid overwriting these files with the `generateNewIcons` process.
+
+> [!caution] 
+> The `currentColor` value should only be added for monochromatic icons. For example, if you export an `IconSystem...` with specific color values, don't add it at all.
+
+#### Wrong icon rendering?
+Before exporting the SVG file:
+1. Detach the symbol instance to avoid destructive actions to the original source component. Use a draft or disposable project document. **Don't detach it** if you are in the original Design System project file
+2. Outline all the present strokes (unless required for dynamic stroke width, but we don't manage this case at the moment)
+3. Select all the different paths and flatten into one. Now you should have a single vector layer.
+4. Make sure your vector path is centered (both vertically and horizontally) in a square
+
+### Add the corresponding key to the `Icon` component
+
 Add the desired key to the `IOIcons` object with the corresponding component reference:
-```jsx
+```tsx
 export const IOIcons = {
   spid: IconSpid,
   …
 }
 ```
-Add the key to the relative icon set:
-```ts
+There's no need to add the new icon in the specific Design System page because it happens automatically.
+
+> [!important]
+> To keep the icons grouped by sets, remember to put the key above the icons with a specific prefix
+
+If the icon belongs to a specific set, add the key to the relative icon set as well:
+```tsx
 export const IONavIcons = {
   navMessages,
   navWallet,
@@ -42,6 +100,8 @@ export const IONavIcons = {
 } as const;
 ```
 
+### Use the new icon in a different component
+
 You can add the recently added icon with the following declaration:
 ```jsx
 // Default size: 24×24px
@@ -51,5 +111,5 @@ You can add the recently added icon with the following declaration:
 
 ## View all the available icons
 There are two ways:
-- In the app, go to the `Profile → Design System → Icons` (you must enable `Debug Mode`)
+- In the main app, go to the `Profile → Design System → Icons` (you must enable `Debug Mode`)
 - In the repository, go to the `svg/originals` subfolder

src/components/pictograms/README.md

@@ -1,29 +1,118 @@
 # Pictograms
-
-## Prefix
-To avoid confusion with other components referenced in the codebase, just use the prefix `Pictogram…`
+There are different sets:
+* **General** 
+* **Objects**: Pictograms that represent object without hands
+* **Bleed**: Pictograms used near the edge of the component's block (w/o inner margins)
 
 ## Add a new pictogram
-First of all, follow the instructions stated in the main README (`Vector graphics` section).
 
-If you want to add a new pictogram, open the `Pictogram.tsx` file and import the React component:
-```jsx
-[…]
-import PictogramAirBaloon from "./svg/PictogramAirBaloon";
-[…]
-```
+### Prerequisites
+
+In your user interface design app (Figma/Sketch) export your SVG with `1×` preset. The name usually consists of a specific prefix followed by the associated key:
+  - **General**: `Pictogram…`
+  - **Objects**: `PictogramObj…`
+  - **Bleed**: `PictogramBleed…`
+
+> [!important]
+> The pictogram must be contained within a `240×240` frame.
+
+> [!tip]
+> If you want to add a new `key` object pictogram, your pictogram will have a `PictogramObjKey` filename. If it doesn't belong to a specific set, you just put the name after the prefix `Pictogram…`, so `PictogramKey`
+
+> [!caution]
+> This filename will be the same as the React component, so make sure you don't already have a component with that filename
+
+### Create the corresponding React component
+
+#### Using `generateNewPictograms.js`
+1. Move the exported file to the `pictograms/svg/originals` folder
+2. In your terminal, in the same folder, run the command: `node generateNewPictograms.js`
+3. The script will process `timestamp.txt`, generate the new React components (with `*.tsx` extension) following exactly the steps listed in the manual process (see below), and process **only the files added after this timestamp value**
+4. If the `generateNewPictograms` script accidentally overwrites older React components, remember to discard the changes before committing
+
+> [!caution] 
+> If your pictogram **contains** other shapes than `path`, you should use the manual process because the script doesn't support this specific case yet (e.g: `Circle`)
+
+#### Manual process (alternative)
+
+1. Move the exported file to the `pictograms/svg/originals` folder
+2. In your original SVG file, delete `width` and `height` attributes and leave the original `viewBox` attribute. You could easily process the image using online editors like [SVGOmg](https://jakearchibald.github.io/svgomg/) (enable `Prefer viewBox to width/height`)
+3. In the `pictograms/svg` folder, create a new React component (with a `.tsx` extension) of the same name
+4. Copy all the `<path>` elements into a new React component and replace the original `<path>` with the element `<Path>` (capital P) from the `react-native-svg` package. Replace all the harcoded fill values with the following corresponding values:
+    * `#0B3EE3` → `{colorValues.hands}`
+    * `#AAEEEF` → `{colorValues.main}`
+    * `#00C5CA` → `{colorValues.secondary}`
+5. Add the dynamic size, replacing the hardcoded values with the corresponding props. The final result should be similar to the following:
+
+    ```tsx
+    import { Svg, Path } from "react-native-svg";
+    // [...]
+
+    const PictogramAttention = ({
+      size,
+      colorValues,
+      ...props
+    }: SVGPictogramProps) => (
+    <Svg width={size} height={size} viewBox="0 0 240 240" {...props}>
+      <Path
+        d="m137.89 157.04…"
+        fill={colorValues.main}
+      />
+      <Path
+        d="M139.17 211.6…"
+        fill={colorValues.hands}
+      />
+    </Svg>
+    );
+    ```
+6. Repeat the previous steps for each pictogram
+7. Once you have finished processing all the new pictograms, run `node generateNewTimestamp` to avoid overwriting these files with the `generateNewPictograms` process.
+
+#### Wrong pictogram rendering?
+Before exporting the SVG file:
+1. Detach the symbol instance to avoid destructive actions to the original source component. Use a draft or disposable project document. **Don't detach it** if you are in the original Design System project file
+2. Outline all the present strokes (unless required for dynamic stroke width, but we don't manage this case at the moment)
+3. Select all the different paths and flatten into one. Now you should have a single vector layer.
+4. Make sure your vector path is centered (both vertically and horizontally) in a square
+
+### Add the corresponding key to the `Pictogram` component
+
 Add the desired key to the `IOPictograms` object with the corresponding component reference:
 ```jsx
 export const IOPictograms = {
-  airBaloon: PictogramAirBaloon,
+  feedback: PictogramFeedback,
   …
 }
 ```
+There's no need to add the new pictogram in the specific Design System page because it happens automatically.
+
+> [!important]
+> To keep the pictograms grouped by sets, remember to put the key above the pictograms with a specific prefix
+
+If the pictogram belongs to a specific set, add the key to the relative pictogram set as well:
+```tsx
+// Destructuring starting from `IOPictograms`
+const { NEW_PICTOGRAM, ibanCard, manual, trash, clock, key, flyingMessage } =
+  IOPictograms;
+
+// Add the new key to the associated object
+export const IOPictogramsObject = {
+  NEW_PICTOGRAM, // ←
+  ibanCard,
+  followMessage,
+  manual,
+  trash,
+  clock,
+  key,
+  flyingMessage
+} as const;
+```
+### Use the new icon in a different component
+
 You can add the recently added pictogram with the following declaration:
 ```jsx
-// Default size: 120×120px
-// Default color: Turquoise
-<Pictogram name="airBaloon">
+// Default size: 120×120
+<Pictogram name="feedback">
 ```
 
 ## View all the available pictograms

src/components/pictograms/generateNewTimestamp.js

@@ -0,0 +1,7 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+const fs = require("fs-extra");
+
+const timestampFilePath = "./timestamp.txt";
+const currentTimestamp = new Date().toISOString();
+
+fs.writeFileSync(timestampFilePath, currentTimestamp);

src/components/typography/README.md

@@ -0,0 +1,23 @@
+# Typography
+
+## Handling font files
+
+The application uses the font _Titillium Web_. Fonts are handled differently than Android and iOS. To use the font, `TitilliumWeb-SemiBoldItalic` example, you must apply the following properties for Android:
+
+```css
+{
+  fontFamily: 'TitilliumWeb-SemiBoldItalic'
+}
+```
+
+while in iOS the code to be applied is:
+
+```css
+{
+  fontFamily: 'Titillium Web',
+  fontWeight: '600',
+  fontStyle: 'italic'
+}
+```
+
+To manage fonts and variants more easily, we have created utility functions within the file [fonts.ts](../../utils/fonts.ts).