diff --git a/docs/Frontend_tutorials/design_system/DS-Validation.md b/docs/Frontend_tutorials/design_system/DS-Validation.md new file mode 100644 index 0000000..14dc675 --- /dev/null +++ b/docs/Frontend_tutorials/design_system/DS-Validation.md @@ -0,0 +1,120 @@ +# Design System Validation + +This document outlines how to validate a design system using an automated workflow powered by **n8n**, with **Figma** as the single source of truth and **Storybook** as the only documentation environment. It is tailored for projects using **Vue** on the frontend, **Ruby** on the backend, and **Tailwind CSS** for layout. + +--- + +## πŸ” Purpose + +- Ensure full alignment between Figma, Storybook and code implementation. +- Catch missing, outdated, or inconsistent components, tokens, and layout structures. +- Automate validation through n8n for scalability and repeatability. +- Guarantee proper documentation coverage in Storybook. + +--- + +## 🧱 What We Validate + +| Area | What We Check | +|----------------------|-------------------------------------------------------------------------| +| **Tokens** | Colors, typography, spacing, elevation, breakpoints, corner radius | +| **Components** | Naming, variants, structure, props, implementation presence | +| **Documentation** | Storybook stories exist and are complete | +| **Tailwind Layout** | Correct usage of utility classes, responsive breakpoints, grid structure| +| **Conventions** | Naming (e.g. `DSButton`), folder structure, reuse consistency | + +--- + +## πŸ” Validation Process (via n8n) + +The validation workflow is automated using **n8n** and follows these steps: + +```plaintext +Start +β†’ Fetch design data from Figma (tokens, components, layout) +β†’ Fetch implementation data from GitLab and Storybook +β†’ Compare each category (tokens, components, layout, docs) +β†’ Generate validation report +``` + +--- + +## 🎨 Figma as Source of Truth + +- Tokens (colors, spacing, typography, breakpoints, border radius) exported via Figma API or plugin +- Components and their variants defined with standard naming and structure +- All layout and grid principles defined in design files + +--- + +## πŸ“š Storybook as Documentation + +- Every coded component must have a Storybook entry +- Stories must demonstrate states (default, hover, disabled, etc.) +- Stories must reflect the component’s Figma structure and naming + +--- + +## πŸ§ͺ Token Validation + +- Tokens from Figma exported as JSON +- Match token name, value, and type (e.g. `primaryColor`, `lineHeightBase`, `smBreakpoint`, `radiusSm`) +- Tokens must be present and correctly used in codebase (SCSS, Tailwind config, utility classes) +- Validate: + - **Colors** (`#HEX`, RGBA, etc.) + - **Typography** (font, size, weight, line height) + - **Spacing** (padding, margin) + - **Elevation** (shadows) + - **Breakpoints** (`sm`, `md`, `lg`, etc.) + - **Corner Radius** (`rounded-sm`, `rounded-lg`, etc.) + +--- + +## 🧩 Component Validation + +### Vue (Frontend) +- Component names start with `DS` prefix (e.g. `DSModal.vue`) +- Props, emits, slots match the Figma structure +- All components have `*.stories.js/ts` in Storybook +- Tailwind classes reflect grid, spacing, breakpoints, and border radius + +### Ruby (Backend) +- Views (`.erb` or `.haml`) use the correct component includes +- Use helpers or partials for reused design elements +- Tailwind utilities consistent with Figma-defined layout and tokens + +--- + +## 🧱 Tailwind Layout Validation + +- Responsive classes (`sm:`, `md:`, `lg:`) reflect design breakpoints +- Grid and flex utilities used correctly (`grid-cols-12`, `gap-4`, etc.) +- Consistent use of spacing (`p-4`, `mb-8`) and corner radius (`rounded-md`) per design tokens + +--- + +## πŸ“© Reporting & Notification + +The n8n workflow posts validation results directly as a comment in the relevant merge request on GitLab. This ensures clear visibility for reviewers and contributors without relying on external channels. + +--- + +## πŸ›  Tools & Integrations + +| Tool | Purpose | +|--------------|-----------------------------------------------| +| **Figma API**| Source of design data (tokens, components) | +| **n8n** | Automate the validation pipeline | +| **GitLab** | Source repo and CI/CD pipeline integration | +| **Storybook**| Documentation and reference implementation | +| **Tailwind** | Utility-first layout and responsive design | + +--- + +## πŸ“† Validation Cadence + +| Task | Frequency | +|-----------------------------|------------------------| +| Automated n8n validation | On every merge request | +| Manual spot-check (QA) | Before releases | +| Full audit | Per sprint | diff --git a/toc.json b/toc.json index 765efa6..71ac847 100644 --- a/toc.json +++ b/toc.json @@ -214,6 +214,17 @@ } ] }, + { + "type": "group", + "title": "Design system", + "items": [ + { + "type": "item", + "title": "Design System Validation", + "uri": "docs/Frontend_tutorials/design_system/DS-Validation.md" + } + ] + }, { "type": "item", "title": "Frontend code generator",