inos/a11y-theme-builder/docs/designers/Understanding-Design-Concepts-…

…Used: updated how to work with tokens file

docs/designers/Understanding-Design-Concepts-Used.md

@@ -0,0 +1,132 @@
+#  Understanding Design Concepts Used In A11Y Theme Builder
+
+**Design tokens** are named variables that store design decisions like colors, fonts, spacing, border styles, and more. Think of them as reusable building blocks for your visual interface. Built on Brad Frost's Atomic Design, this a11y theme builder generates design tokens in **CSS** and **JSON** formats.
+
+# Atomic Design 
+
+Atomic Design is a design system methodology created by Brad Frost. It offers a structured approach to building user interfaces by breaking them down into their smallest, reusable components. This promotes consistency, scalability, and improves collaboration between designers and developers.
+
+## Atoms
+
+ Atoms are the fundamental building blocks of this design system. They represent the most basic visual elements that can't be further broken down. Here's a breakdown of atom categories provided:
+
+-   **Color Palette:**
+
+    -   **Theme Colors:** The core set of colors representing your brand identity (e.g., primary, secondary, accent).
+    -   **Sub-themes:** Variations on your core theme colors (e.g., dark theme, light theme palettes).
+
+-   **Typography:**
+
+    -   **Font Families:** Define the base fonts used throughout your interface.
+    -   **Style Settings:**
+
+        -   **Display Styles:** High-impact text styles for headings (e.g., H1, H2, etc.).
+        -   **Header Styles:** Bold and clear styles for headers within sections.
+        -   **Body Text Styles:** The primary font styles for paragraphs and regular text.
+        -   **Stat Styles:** Specific styles for presenting data (e.g., numbers, percentages).
+
+
+-   **Shadow Atoms:**
+
+    -   **Elevation:** Define elevation levels to create a sense of depth and hierarchy between elements (e.g., drop shadows, card shadows).
+    -   **Bevel:** Control how an element's edges are styled (e.g., soft bevels for buttons).
+    -   **Inner Shadow:** Add depth within an element using inner shadows.
+    -   **Outer Glow:** Create an outer glow effect around elements.
+
+-   **Other Atoms:**
+
+    -   **Grid System:** Define your layout grid for consistent spacing and responsive design.
+    -   **Target States:** Visual styles for interactive elements like buttons (e.g., hover, focus states).
+    -   **Chart Colors:** Color palettes specifically designed for data visualizations.
+    -   **Border Settings:** Establish border styles (e.g., thickness, color) for various use cases.
+    -   **Hotlink Styles:** Visual indicators for hyperlinks (e.g., underline, color).
+    -   **Input Background:** Styles for input fields and textareas.
+    -   **Animation Settings:** Define animation properties for dynamic transitions and micro-interactions.
+
+    - Find complete list of properties here - https://finos.github.io/a11y-theme-builder-sdk/classes/Atom.html
+
+##  Molecules
+
+Molecules are combinations of atoms that create simple, functional units. They represent slightly more complex structures within your design system, providing a bridge between basic visual elements (atoms) and more complex components (organisms)
+
+-   **General Desktop**
+
+    The **General Desktop** category includes various interactive and static elements commonly used in desktop applications.
+ -   **Avatars:** Visual representations of users or entities, typically circular images or icons.
+-   **Buttons:**
+    -   **Standard Buttons:** Default interactive buttons used for various actions.
+    -   **Small Buttons:** Smaller variants of standard buttons for less prominent actions.
+-   **Cards:** Container elements that group related information together, often with a shadow and border.
+-   **Chips:** Small, interactive elements used for input, filters, or selections.
+-   **Dropdowns:** Expandable lists for selecting one option from multiple choices.
+-   **Images:** Static visual elements used to display pictures or graphics.
+-   **Modals:** Overlay windows that display content without leaving the current page.
+-   **Spacing:** Elements that define consistent spacing between components.
+-   **Popovers:** Small overlays that display additional information when an element is hovered or clicked.
+-   **Sliders:** Interactive controls for selecting values within a range.
+-   **Toasts:** Small notifications that provide feedback to the user.
+
+### Charts
+
+The **Charts** category includes various types of data visualizations.
+
+-   **Donut Charts:** Circular charts that represent data as segments of a donut.
+-   **Pie Charts:** Circular charts that represent data as slices of a pie.
+-   **Bar Charts:** Charts that use rectangular bars to represent data values.
+-   **Line Charts:** Charts that use lines to connect data points and show trends over time.
+-   **Progress Bars:** Visual indicators that show the completion status of a task or process.
+
+    - Find complete list of properties here -     - https://finos.github.io/a11y-theme-builder-sdk/classes/Molecules.html
+
+  ##  Organisms
+
+Organisms are more complex components composed of multiple molecules. They form distinct sections of the user interface, integrating various atoms and molecules to create cohesive and functional elements.
+
+### Text
+Organisms that focus on textual content and its presentation.  
+
+### Images
+
+Organisms that involve images and their presentation.
+
+### Videos
+
+Organisms for presenting video content.
+
+### Lists
+
+Organisms that involve lists of items:
+
+-   **Center-Aligned Lists:** Lists with items centered within the container.
+-   **List with Image Left:** Lists where each item includes an image aligned to the left.
+-   **Standard Lists:** Vertical or horizontal lists of items.
+
+### Cards
+
+Organisms composed of multiple card molecules:
+
+-   **Card Grids:** Collections of cards displayed in a grid layout.
+-   **Card with Header, Content, and Footer:** Cards structured with distinct header, content, and footer sections.
+
+### Other Complex Components
+
+More complex organisms that combine various elements:
+
+1.  **Hero Section:**
+
+    -   A prominent section at the top of a page, often featuring a large background image, heading, subheading, and call-to-action buttons.
+2.  **Footer:**
+
+    -   The bottom section of a page, typically containing navigation links, contact information, and social media icons.
+3.  **Teams Section:**
+
+    -   A section showcasing team members with their photos, names, and roles.
+4.  **Feature Highlights:**
+
+    -   Sections highlighting key features or benefits, often using icons, headings, and descriptive text.
+5.  **Testimonial Section:**
+
+    -   A section featuring customer testimonials, typically including quotes, customer names, and photos.    
+
+   Find complete list of properties here - https://finos.github.io/a11y-theme-builder-sdk/classes/Organism.html
+

docs/designers/how-to-work-with-tokens.md

@@ -4,3 +4,254 @@
 
 >If you are interested in helping us document this feature, please see our [call for contributors](../contribute/index.md).
 
+#  Using Design Tokens Generated by the a11y Theme Builder
+
+**Design tokens** generated by the a11y theme builder are provided in a structured JSON format. These tokens encapsulate design decisions such as colors, typography, spacing, and more, which can be directly used in your project's stylesheets and code.
+
+### JSON Structure
+
+The generated JSON file is structured into various sections, each corresponding to different aspects of your design system:
+
+-   **Atoms**
+-   **Molecules**
+-   **Organisms**
+-   **Layers**
+-   **Metadata**
+
+### Example JSON Structure
+```
+{
+    "atoms": {
+        "colorPalette": {
+            "colors": [
+                {
+                    "name": "Teal",
+                    "hex": "#3fb394"
+                }
+            ],
+            "defaultColorName": "Teal"
+        },
+        ...
+    },
+    "molecules": {
+        "avatars": {},
+        ...
+    },
+    "organisms": {
+        "dataTables": {},
+        ...
+    },
+    "layers": {},
+    "metadata": {
+        ...
+    },
+    "id": "My Design"
+}
+ ```
+ ### Working with Design Tokens
+
+#### Atoms
+
+Atoms are the basic building blocks of your design system. They include color palettes, typography, spacing, and more.
+
+**Color Palette Example:**
+``` 
+{
+    "colorPalette": {
+        "colors": [
+            {
+                "name": "Teal",
+                "hex": "#3fb394"
+            }
+        ],
+        "defaultColorName": "Teal"
+    }
+}
+```
+To use this color in your CSS:
+``` 
+:root {
+    --color-teal: #3fb394;
+}
+
+body {
+    background-color: var(--color-teal);
+}
+```
+**Typography Example:**
+```
+{
+    "fontsSettings": {
+        "baseFontSize": 16,
+        "fontWeights": [
+            300,
+            400,
+            600,
+            700,
+            800
+        ]
+    }
+}
+```
+To use these font settings in your CSS:
+```
+:root {
+    --base-font-size: 16px;
+    --font-weight-regular: 400;
+    --font-weight-bold: 700;
+}
+
+body {
+    font-size: var(--base-font-size);
+    font-weight: var(--font-weight-regular);
+}
+
+h1 {
+    font-weight: var(--font-weight-bold);
+}
+```
+#### Molecules
+
+Molecules combine atoms to form more complex components like buttons, dropdowns, and sliders.
+
+**Button Example:**
+ ```
+ {
+    "standardButtons": {
+        "minWidth": 6
+    }
+}
+```
+To use this button setting in your CSS:
+```
+ button.standard {
+    min-width: 6rem;
+}
+```
+**Chart Example:**
+```
+{
+    "chartDonut": {
+        "cutoutThickness": {
+            "min": 0,
+            "max": 100
+            }
+        }
+    }
+}
+```
+To use this chart setting in your JavaScript chart configuration:
+```
+const donutChartConfig = {
+    type: 'doughnut',
+    data: {...},
+    options: {
+        cutoutPercentage: 50 // Use a value between min and max
+    }
+};
+```
+#### Organisms
+
+Organisms are complex components made up of multiple molecules. Examples include data tables, navigation bars, and footers.
+
+**Navigation Bar Example:**
+```
+{
+    "primaryNav": {}
+}
+```
+To use this navigation bar in your HTML and CSS:
+
+```
+<nav class="primary-nav">
+    <!-- Navigation items here -->
+</nav>
+```
+```
+.primary-nav {
+    /* Add your styles here */
+}
+```
+#### Metadata
+
+Metadata provides additional information about the design tokens, such as creation and update timestamps, and overall color settings.
+
+**Metadata Example:**
+```
+{
+    "metadata": {
+        "sample": false,
+        "time": {
+            "createdInMs": 1681464745221,
+            "lastUpdateInMs": 1698766878813
+        },
+        "colors": {
+            "primary": "#339779",
+            "secondary": "#3FB394",
+            "tertiary": "#75C8B2",
+            "background": "#F6FBFA"
+        }
+    }
+}
+```
+This information can be used for versioning or auditing purposes.
+
+### How to Work with Design Tokens
+
+#### Step 1: Extract the JSON File
+
+First, ensure you have the JSON file generated by the a11y theme builder. This file contains all the design tokens you'll need for your project.
+
+#### Step 2: Import the JSON File
+
+Import the JSON file into your project. This can be done in various ways depending on your project's setup.
+
+**Example using JavaScript:**
+```
+import designTokens from './path/to/design-tokens.json';
+```
+#### Step 3: Convert JSON to CSS Variables
+
+You can convert the JSON tokens to CSS variables for easy use in your stylesheets.
+
+**Example using JavaScript:**
+```
+const root = document.documentElement;
+
+const setCSSVariables = (tokens) => {
+    Object.keys(tokens).forEach(key => {
+        const value = tokens[key];
+        if (typeof value === 'object') {
+            setCSSVariables(value);
+        } else {
+            root.style.setProperty(`--${key}`, value);
+        }
+    });
+};
+
+setCSSVariables(designTokens.atoms.colorPalette.colors[0]);
+```
+#### Step 4: Use CSS Variables in Your Stylesheets
+
+Once the tokens are converted to CSS variables, you can use them throughout your stylesheets.
+
+**Example using CSS:**
+```git 
+body {
+    background-color: var(--hex);
+}
+```
+#### Step 5: Utilize Tokens in Component Styles
+
+Integrate the design tokens into your component styles to ensure consistency across your project.
+
+**Example using React:**
+```
+const Button = () => {
+    return (
+        <button style={{ backgroundColor: 'var(--color-teal)' }}>
+            Click Me
+        </button>
+    );
+};
+```