From 7779908e579ec326b5ed6e032b12484e172fb966 Mon Sep 17 00:00:00 2001 From: vaclavstencl Date: Tue, 6 May 2025 14:52:17 +0200 Subject: [PATCH] feat: add design system validation docs Added comprehensive design system validation documentation. Includes detailed validation process for tokens, components, and layouts using n8n automation with Figma and Storybook integration. Covers Vue frontend and Ruby backend implementation details. --- .../design_system/DS-Validation.md | 120 ++++++++++++++++++ toc.json | 11 ++ 2 files changed, 131 insertions(+) create mode 100644 docs/Frontend_tutorials/design_system/DS-Validation.md 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",