Skip to content
This repository was archived by the owner on May 6, 2026. It is now read-only.

Commit 7779908

Browse files
author
vaclavstencl
committed
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.
1 parent 0726e4f commit 7779908

2 files changed

Lines changed: 131 additions & 0 deletions

File tree

‎docs/Frontend_tutorials/design_system/DS-Validation.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Design System Validation
2+
3+
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.
4+
5+
---
6+
7+
## 🔍 Purpose
8+
9+
- Ensure full alignment between Figma, Storybook and code implementation.
10+
- Catch missing, outdated, or inconsistent components, tokens, and layout structures.
11+
- Automate validation through n8n for scalability and repeatability.
12+
- Guarantee proper documentation coverage in Storybook.
13+
14+
---
15+
16+
## 🧱 What We Validate
17+
18+
| Area | What We Check |
19+
|----------------------|-------------------------------------------------------------------------|
20+
| **Tokens** | Colors, typography, spacing, elevation, breakpoints, corner radius |
21+
| **Components** | Naming, variants, structure, props, implementation presence |
22+
| **Documentation** | Storybook stories exist and are complete |
23+
| **Tailwind Layout** | Correct usage of utility classes, responsive breakpoints, grid structure|
24+
| **Conventions** | Naming (e.g. `DSButton`), folder structure, reuse consistency |
25+
26+
---
27+
28+
## 🔁 Validation Process (via n8n)
29+
30+
The validation workflow is automated using **n8n** and follows these steps:
31+
32+
```plaintext
33+
Start
34+
→ Fetch design data from Figma (tokens, components, layout)
35+
→ Fetch implementation data from GitLab and Storybook
36+
→ Compare each category (tokens, components, layout, docs)
37+
→ Generate validation report
38+
```
39+
40+
---
41+
42+
## 🎨 Figma as Source of Truth
43+
44+
- Tokens (colors, spacing, typography, breakpoints, border radius) exported via Figma API or plugin
45+
- Components and their variants defined with standard naming and structure
46+
- All layout and grid principles defined in design files
47+
48+
---
49+
50+
## 📚 Storybook as Documentation
51+
52+
- Every coded component must have a Storybook entry
53+
- Stories must demonstrate states (default, hover, disabled, etc.)
54+
- Stories must reflect the component’s Figma structure and naming
55+
56+
---
57+
58+
## 🧪 Token Validation
59+
60+
- Tokens from Figma exported as JSON
61+
- Match token name, value, and type (e.g. `primaryColor`, `lineHeightBase`, `smBreakpoint`, `radiusSm`)
62+
- Tokens must be present and correctly used in codebase (SCSS, Tailwind config, utility classes)
63+
- Validate:
64+
- **Colors** (`#HEX`, RGBA, etc.)
65+
- **Typography** (font, size, weight, line height)
66+
- **Spacing** (padding, margin)
67+
- **Elevation** (shadows)
68+
- **Breakpoints** (`sm`, `md`, `lg`, etc.)
69+
- **Corner Radius** (`rounded-sm`, `rounded-lg`, etc.)
70+
71+
---
72+
73+
## 🧩 Component Validation
74+
75+
### Vue (Frontend)
76+
- Component names start with `DS` prefix (e.g. `DSModal.vue`)
77+
- Props, emits, slots match the Figma structure
78+
- All components have `*.stories.js/ts` in Storybook
79+
- Tailwind classes reflect grid, spacing, breakpoints, and border radius
80+
81+
### Ruby (Backend)
82+
- Views (`.erb` or `.haml`) use the correct component includes
83+
- Use helpers or partials for reused design elements
84+
- Tailwind utilities consistent with Figma-defined layout and tokens
85+
86+
---
87+
88+
## 🧱 Tailwind Layout Validation
89+
90+
- Responsive classes (`sm:`, `md:`, `lg:`) reflect design breakpoints
91+
- Grid and flex utilities used correctly (`grid-cols-12`, `gap-4`, etc.)
92+
- Consistent use of spacing (`p-4`, `mb-8`) and corner radius (`rounded-md`) per design tokens
93+
94+
---
95+
96+
## 📩 Reporting & Notification
97+
98+
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.
99+
100+
---
101+
102+
## 🛠 Tools & Integrations
103+
104+
| Tool | Purpose |
105+
|--------------|-----------------------------------------------|
106+
| **Figma API**| Source of design data (tokens, components) |
107+
| **n8n** | Automate the validation pipeline |
108+
| **GitLab** | Source repo and CI/CD pipeline integration |
109+
| **Storybook**| Documentation and reference implementation |
110+
| **Tailwind** | Utility-first layout and responsive design |
111+
112+
---
113+
114+
## 📆 Validation Cadence
115+
116+
| Task | Frequency |
117+
|-----------------------------|------------------------|
118+
| Automated n8n validation | On every merge request |
119+
| Manual spot-check (QA) | Before releases |
120+
| Full audit | Per sprint |

‎toc.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -214,6 +214,17 @@
214214
}
215215
]
216216
},
217+
{
218+
"type": "group",
219+
"title": "Design system",
220+
"items": [
221+
{
222+
"type": "item",
223+
"title": "Design System Validation",
224+
"uri": "docs/Frontend_tutorials/design_system/DS-Validation.md"
225+
}
226+
]
227+
},
217228
{
218229
"type": "item",
219230
"title": "Frontend code generator",

0 commit comments

Comments
 (0)