@tetjana/flowmakers-ds 0.1.6 → 0.1.7

package/dist/components/Button.figma.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/Checkbox.figma.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/Input.figma.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/Tag.figma.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/Toggle.figma.d.ts

@@ -0,0 +1 @@
+export {};

package/guidelines/Guidelines.md

@@ -0,0 +1,36 @@
+# FlowMakers Design System Guidelines
+
+This project uses the **FlowMakers Design System** installed via `@tetjana/flowmakers-ds`.
+
+## IMPORTANT — Always read first:
+- All files starting with `overview-` in this folder
+- All files in the `design-tokens/` folder:
+  - `design-tokens/colors.md`
+  - `design-tokens/typography.md`
+  - `design-tokens/spacing.md`
+
+## Read before using a component:
+Open `guidelines/components/{ComponentName}.md` BEFORE writing any code with that component.
+
+## Available components
+- `Button` → `guidelines/components/button.md`
+- `Input` → `guidelines/components/input.md`
+- `Tag` → `guidelines/components/tag.md`
+- `Toggle` → `guidelines/components/toggle.md`
+- `Checkbox` → `guidelines/components/checkbox.md`
+- `Header` → `guidelines/components/header.md`
+- `Footer` → `guidelines/components/footer.md`
+
+## Rules
+1. **Always prefer FlowMakers components** over native HTML elements (e.g. use `<Button>` not `<button>`)
+2. **Never override component styles** with inline styles or className unless strictly necessary
+3. **Always use CSS variables** from the design tokens for colors, spacing, and typography
+4. **Fonts**: Manrope (headings) and Nunito Sans (body/UI) — import from Google Fonts
+5. **Always import styles**: `import '@tetjana/flowmakers-ds/styles'` must be in the entry file
+
+## Steps before writing code
+1. Read `overview-components.md`
+2. Read all files in `design-tokens/`
+3. Identify which components you need
+4. Read each component's `.md` file in `guidelines/components/`
+5. Write the code using only FlowMakers components and tokens

package/guidelines/components/button.md

@@ -0,0 +1,50 @@
+# Button
+
+**Import**: `import { Button } from '@tetjana/flowmakers-ds'`
+
+## Variants
+| Variant          | Appearance                          | Use for                          |
+|------------------|-------------------------------------|----------------------------------|
+| `primary`        | Black bg, white text                | Main CTA actions                 |
+| `hero`           | Black bg, pink border on hover      | Landing page main CTA            |
+| `secondary`      | Transparent, black border           | Secondary actions                |
+| `secondary-large`| Same but taller (52px)              | Prominent secondary actions      |
+| `ghost`          | No border, no bg                    | Tertiary, low-emphasis actions   |
+| `ghost-icon`     | Icon-only ghost button              | Toolbar icons, small actions     |
+
+## Sizes
+| Size  | Height | Use for              |
+|-------|--------|----------------------|
+| `sm`  | 32px   | Compact UI, tables   |
+| `md`  | 42px   | Default (most cases) |
+| `lg`  | 52px   | Landing pages        |
+
+## Props
+| Prop        | Type            | Default     | Description               |
+|-------------|-----------------|-------------|---------------------------|
+| `variant`   | ButtonVariant   | `'primary'` | Visual style              |
+| `size`      | ButtonSize      | `'md'`      | Height/padding            |
+| `leftIcon`  | ReactNode       | —           | Icon before text          |
+| `rightIcon` | ReactNode       | —           | Icon after text           |
+| `fullWidth` | boolean         | `false`     | Stretch to container      |
+| `disabled`  | boolean         | `false`     | Disabled state            |
+
+## Examples
+```tsx
+// Primary
+<Button>Почати тренування</Button>
+
+// Secondary with icon
+<Button variant="secondary" leftIcon={<PlusIcon />}>Додати</Button>
+
+// Disabled
+<Button disabled>Недоступно</Button>
+
+// Full width
+<Button fullWidth>Зареєструватись</Button>
+```
+
+## Do NOT
+- Do not use native `<button>` — always use `<Button>`
+- Do not add className to change colors
+- Do not use `primary` for destructive actions — use a red-tinted secondary instead

package/guidelines/components/checkbox.md

@@ -0,0 +1,51 @@
+# Checkbox
+
+**Import**: `import { Checkbox } from '@tetjana/flowmakers-ds'`
+
+## Description
+Чекбокс для вибору одного або кількох варіантів. Підтримує indeterminate стан.
+
+## Props
+| Prop            | Type                       | Required | Default   | Description                          |
+|-----------------|----------------------------|----------|-----------|--------------------------------------|
+| `checked`       | boolean                    | no       | `false`   | Checked state                        |
+| `indeterminate` | boolean                    | no       | `false`   | Mixed state (overrides checked icon) |
+| `onChange`      | (checked: boolean) => void | no       | —         | Called when user clicks              |
+| `label`         | string                     | no       | —         | Text label next to checkbox          |
+| `size`          | `'small'` \| `'large'`    | no       | `'small'` | Box size (16px vs 22px)              |
+| `disabled`      | boolean                    | no       | `false`   | Prevents interaction                 |
+
+## Visual
+- **Unchecked** → white box, grey border
+- **Checked** → blue fill (`#0d6fff`), white checkmark SVG
+- **Indeterminate** → blue fill, white minus bar
+- **Disabled** → 50% opacity, no pointer events
+
+## Examples
+```tsx
+// Simple checkbox with label
+const [agreed, setAgreed] = useState(false);
+<Checkbox
+  checked={agreed}
+  onChange={setAgreed}
+  label="Я погоджуюсь з умовами використання"
+/>
+
+// Large size
+<Checkbox size="large" checked={selected} onChange={setSelected} label="Вибрати всіх" />
+
+// Indeterminate (partial selection)
+<Checkbox
+  indeterminate={someSelected && !allSelected}
+  checked={allSelected}
+  onChange={toggleAll}
+  label="Вибрати всіх"
+/>
+
+// Disabled
+<Checkbox checked={true} disabled label="Незмінний параметр" />
+```
+
+## Do NOT
+- Do NOT use for on/off single switches — use `Toggle` instead
+- Do NOT rely on CSS classes for checked state — always use `checked` prop

package/guidelines/components/footer.md

@@ -0,0 +1,63 @@
+# Footer
+
+**Import**: `import { Footer } from '@tetjana/flowmakers-ds'`
+
+## Description
+Footer сторінки з CTA-блоком та секціями посилань. Підтримує light і dark теми.
+
+## Props
+| Prop          | Type              | Required | Default                                   | Description                              |
+|---------------|-------------------|----------|-------------------------------------------|------------------------------------------|
+| `variant`     | `'light'` \| `'dark'` | no   | `'light'`                                 | Light (white bg) or dark (black bg)      |
+| `headline`    | string            | no       | `'Є ідеї чи пропозиції?'`                | CTA heading on the left side             |
+| `ctaLabel`    | string            | no       | `'Написати нам'`                          | CTA button text                          |
+| `onCtaClick`  | () => void        | no       | —                                         | CTA button click handler                 |
+| `sections`    | FooterSection[]   | no       | `[]`                                      | Link columns (title + links)             |
+| `copyright`   | string            | no       | `'© 2024 Made by FlowMakers...'`         | Bottom copyright line                    |
+
+## Types
+```tsx
+interface FooterLink    { label: string; href: string; }
+interface FooterSection { title: string; links: FooterLink[]; }
+```
+
+## Visual
+- **Light**: white/grey bg, black text, black CTA button
+- **Dark**: `#18181b` bg, white text (75% opacity), outlined CTA with pink border
+
+## Examples
+```tsx
+// Minimal light footer
+<Footer />
+
+// Dark footer with sections
+<Footer
+  variant="dark"
+  headline="Долучайся до FlowMakers"
+  ctaLabel="Розпочати безкоштовно"
+  onCtaClick={() => navigate('/register')}
+  sections={[
+    {
+      title: 'Продукт',
+      links: [
+        { label: 'Про нас',    href: '/about' },
+        { label: 'Функції',    href: '/features' },
+        { label: 'Тарифи',     href: '/pricing' },
+      ],
+    },
+    {
+      title: 'Підтримка',
+      links: [
+        { label: 'FAQ',        href: '/faq' },
+        { label: 'Контакти',   href: '/contact' },
+      ],
+    },
+  ]}
+  copyright="© 2025 FlowMakers. Всі права захищені."
+/>
+```
+
+## Do NOT
+- Do NOT add more than 3–4 sections — it breaks the layout
+- Do NOT use Footer inside a card or modal — it is a page-level component
+- Do NOT put interactive forms inside Footer — keep it to links and CTA only

package/guidelines/components/header.md

@@ -0,0 +1,57 @@
+# Header
+
+**Import**: `import { Header } from '@tetjana/flowmakers-ds'`
+
+## Description
+Заголовок картки/віджета з title, необов'язковим subtitle і слотами для іконок/дій зліва і справа.
+Використовується як верхня частина інформаційних блоків і дашборд-карток.
+
+## Props
+| Prop        | Type                    | Required | Default    | Description                           |
+|-------------|-------------------------|----------|------------|---------------------------------------|
+| `title`     | string                  | ✅ yes   | —          | Main heading text                     |
+| `subtitle`  | string                  | no       | —          | Secondary text below the title        |
+| `color`     | `'purple'` \| `'grey'` | no       | `'purple'` | Background color                      |
+| `leftSlot`  | ReactNode               | no       | —          | Icon or element on the left           |
+| `rightSlot` | ReactNode               | no       | —          | Action button or icon on the right    |
+
+## Color backgrounds
+| Color    | Background token        | Hex       | Use for                              |
+|----------|-------------------------|-----------|--------------------------------------|
+| `purple` | `--primary-fill-100`   | `#eeecfb` | Default, most widgets and cards      |
+| `grey`   | `--nature-fill-50`     | `#f7f7f8` | Secondary cards, settings sections   |
+
+## Visual
+- Rounded top corners (`border-radius: 20px 20px 0 0`)
+- Uses **Manrope Bold 18px** for title
+- Uses **Nunito Sans Regular 14px** for subtitle in muted grey
+
+## Examples
+```tsx
+// Basic
+<Header title="Мій профіль" />
+
+// With subtitle
+<Header title="Аналітика" subtitle="Ваш прогрес за останній місяць" />
+
+// Grey background with icons
+<Header
+  color="grey"
+  title="Налаштування"
+  leftSlot={<SettingsIcon />}
+  rightSlot={<Button variant="ghost-icon"><EditIcon /></Button>}
+/>
+
+// Full widget pattern (Header + content inside a card)
+<div style={{ borderRadius: '20px', border: '1px solid var(--bw-fill-100)' }}>
+  <Header title="Оцінки" subtitle="Останні результати" />
+  <div style={{ padding: '16px' }}>
+    {/* widget content */}
+  </div>
+</div>
+```
+
+## Do NOT
+- Do NOT use Header as a page `<h1>` — it is for widget/card headers only
+- Do NOT put long text in subtitle — keep it to one short line
+- Do NOT change background via className — use the `color` prop

package/guidelines/components/input.md

@@ -0,0 +1,39 @@
+# Input
+
+**Import**: `import { Input } from '@tetjana/flowmakers-ds'`
+
+## States
+`default` → `hover` → `focused` → `filled` → `error` / `success`
+
+## Props
+| Prop             | Type        | Default     | Description                   |
+|------------------|-------------|-------------|-------------------------------|
+| `label`          | string      | —           | Label above the input         |
+| `placeholder`    | string      | —           | Placeholder text              |
+| `state`          | InputState  | `'default'` | Visual state                  |
+| `errorMessage`   | string      | —           | Shown when state=error        |
+| `successMessage` | string      | —           | Shown when state=success      |
+| `leftIcon`       | ReactNode   | —           | Icon inside left side         |
+| `rightIcon`      | ReactNode   | —           | Icon inside right side        |
+| `disabled`       | boolean     | `false`     | Disabled state                |
+
+## Examples
+```tsx
+// Email input
+<Input label="Електронна пошта" placeholder="Введіть Вашу електронну пошту" type="email" />
+
+// With error
+<Input
+  label="Пароль"
+  type="password"
+  state="error"
+  errorMessage="Невірний пароль"
+/>
+
+// With success
+<Input label="Email" state="success" successMessage="Email підтверджено" />
+```
+
+## Do NOT
+- Do not use native `<input>` for form fields — always use `<Input>`
+- Do not manually change border color with CSS — use the `state` prop

package/guidelines/components/tag.md

@@ -0,0 +1,27 @@
+# Tag
+
+**Import**: `import { Tag } from '@tetjana/flowmakers-ds'`
+
+## Colors
+| Color    | Background        | Text              | Use for                     |
+|----------|-------------------|-------------------|-----------------------------|
+| `grey`   | `#eeeef0`         | `#4c4d58`         | Neutral labels, duration    |
+| `green`  | `#d9f2e7`         | `#1b6153`         | Success, available, done    |
+| `yellow` | `#fff0d4`         | `#c54e09`         | Warning, in progress        |
+| `purple` | `#eeecfb`         | `#6d45bc`         | Category, feature label     |
+| `pink`   | `#ffe7fc`         | `#b51692`         | Special, premium            |
+
+## Props
+| Prop       | Type      | Default  | Description          |
+|------------|-----------|----------|----------------------|
+| `color`    | TagColor  | `'grey'` | Color variant        |
+| `children` | ReactNode | —        | Tag label text       |
+
+## Examples
+```tsx
+<Tag>5 хв</Tag>
+<Tag color="green">Завершено</Tag>
+<Tag color="yellow">В процесі</Tag>
+<Tag color="purple">AI</Tag>
+<Tag color="pink">Premium</Tag>
+```

package/guidelines/components/toggle.md

@@ -0,0 +1,41 @@
+# Toggle
+
+**Import**: `import { Toggle } from '@tetjana/flowmakers-ds'`
+
+## Description
+Перемикач on/off. Обов'язково потребує контрольованого стану (`checked` + `onChange`).
+
+## Props
+| Prop        | Type                       | Required | Default | Description                   |
+|-------------|----------------------------|----------|---------|-------------------------------|
+| `checked`   | boolean                    | ✅ yes   | —       | Current on/off state          |
+| `onChange`  | (checked: boolean) => void | ✅ yes   | —       | Called when user toggles      |
+| `label`     | string                     | no       | —       | Text label next to the toggle |
+| `disabled`  | boolean                    | no       | `false` | Prevents interaction          |
+
+## Visual
+- **Off** → grey track, white thumb
+- **On** → gradient track (pink→yellow→mint→purple), white thumb, animated
+- **Disabled** → 50% opacity, no pointer events
+
+## Examples
+```tsx
+// Controlled toggle with useState
+const [enabled, setEnabled] = useState(false);
+<Toggle
+  checked={enabled}
+  onChange={setEnabled}
+  label="Отримувати сповіщення"
+/>
+
+// Disabled
+<Toggle checked={false} onChange={() => {}} disabled label="Недоступно" />
+
+// Without label (icon-only row)
+<Toggle checked={active} onChange={setActive} />
+```
+
+## Do NOT
+- Do NOT use without `checked` + `onChange` — the component is always controlled
+- Do NOT use for multi-option selection — use `Checkbox` instead
+- Do NOT change the track color via CSS — the gradient is part of the brand style

package/guidelines/design-tokens/colors.md

@@ -0,0 +1,42 @@
+# Color Tokens
+
+All colors are CSS variables. Import `@tetjana/flowmakers-ds/styles` to use them.
+
+## Primary palette (Purple)
+| Token                       | Value     | Use for                              |
+|-----------------------------|-----------|--------------------------------------|
+| `--primary-fill-100`        | `#eeecfb` | Light purple backgrounds, tag bg     |
+| `--primary-fill-500`        | `#7d65e1` | Focus rings, active checkboxes       |
+| `--primary-fill-600`        | `#6d45bc` | Hover states on purple elements      |
+| `--primary-fill-700`        | `#6d45bc` | Purple tag text                      |
+
+## Black & White
+| Token                       | Value     | Use for                              |
+|-----------------------------|-----------|--------------------------------------|
+| `--bw-fill-black`           | `#121212` | Primary buttons, headings, body text |
+| `--bw-fill-white`           | `#ffffff` | Backgrounds, button text on dark     |
+| `--bw-fill-50`              | `#f7f7f8` | Page background, grey header         |
+| `--bw-fill-100`             | `#eeeef0` | Hover backgrounds                    |
+| `--bw-fill-200`             | `#dcdcdc` | Disabled button background           |
+| `--bw-fill-300`             | `#b8b9c1` | Input borders (default)              |
+| `--bw-fill-400`             | `#989898` | Subtitle, secondary text             |
+| `--bw-fill-500`             | `#7c7c7c` | Muted text                           |
+
+## Accent colors
+| Token                       | Value     | Use for                              |
+|-----------------------------|-----------|--------------------------------------|
+| `--pink-fill-100`           | `#ffe7fc` | Pink tag background                  |
+| `--pink-fill-300`           | `#ffa8f1` | Hero button hover border             |
+| `--pink-fill-700`           | `#b51692` | Pink tag text                        |
+| `--green-fill-100`          | `#d9f2e7` | Green tag background, success tint   |
+| `--green-fill-500`          | `#27a872` | Success input border                 |
+| `--green-fill-700`          | `#1b6153` | Green tag text                       |
+| `--yellow-fill-100`         | `#fff0d4` | Yellow tag background, warning tint  |
+| `--yellow-fill-700`         | `#c54e09` | Yellow tag text                      |
+
+## Decision tree
+- Need a background? → Start with `--bw-fill-50` or `--primary-fill-100`
+- Need text on white? → Use `--bw-fill-black`
+- Need muted/secondary text? → Use `--bw-fill-400`
+- Need a border? → Use `--bw-fill-300` (default) or `--primary-fill-500` (focused)
+- Need a status color? → Use the matching `--green`, `--yellow`, or `--pink` token

package/guidelines/design-tokens/spacing.md

@@ -0,0 +1,41 @@
+# Spacing & Border Radius Tokens
+
+All tokens are CSS variables available after `import '@tetjana/flowmakers-ds/styles'`.
+
+## Spacing scale
+| Token          | Value | Use for                                           |
+|----------------|-------|---------------------------------------------------|
+| `--space-xxs`  | 4px   | Icon gaps, tiny internal padding                  |
+| `--space-xs`   | 8px   | Between icon and text, small card gaps            |
+| `--space-s`    | 10px  | Button padding (sm), tight list items             |
+| `--space-sm`   | 12px  | Between label and input, small section gaps       |
+| `--space-m`    | 16px  | Default padding inside cards, between form fields |
+| `--space-l`    | 20px  | Card/widget internal padding                      |
+| `--space-xl`   | 24px  | Section padding, between major blocks             |
+| `--space-2xl`  | 32px  | Large gaps, between sections                      |
+| `--space-3xl`  | 48px  | Between major page sections                       |
+
+## Border radius scale
+| Token          | Value  | Use for                                      |
+|----------------|--------|----------------------------------------------|
+| `--radius-xs`  | 8px    | Small chips, badges, compact inputs          |
+| `--radius-s`   | 10px   | Buttons (sm), small cards                    |
+| `--radius-m`   | 12px   | Buttons (md/lg), inputs, standard cards      |
+| `--radius-l`   | 16px   | Large cards, modals                          |
+| `--radius-xl`  | 20px   | Widget containers, Header component          |
+| `--radius-full`| 9999px | Pills, Tags, Toggle track, Avatar circles    |
+
+## Rules
+- Always use `--space-*` tokens instead of hardcoded pixel values
+- For card padding: use `var(--space-m, 16px)` as the default fallback
+- For inner component spacing: `--space-xs` (8px) or `--space-sm` (12px)
+- For section-level gaps: `--space-xl` (24px) or `--space-2xl` (32px)
+
+## Example
+```css
+.my-card {
+  padding: var(--space-m);
+  border-radius: var(--radius-l);
+  gap: var(--space-sm);
+}
+```

package/guidelines/design-tokens/typography.md

@@ -0,0 +1,23 @@
+# Typography Tokens
+
+## Font families
+- **Headings**: `Manrope` (Bold 700) — page titles, widget titles, display text
+- **Body & UI**: `Nunito Sans` — all other text (labels, body, buttons, captions)
+
+## Font size scale
+| Token                | Value  | Class          | Use for                        |
+|----------------------|--------|----------------|--------------------------------|
+| `--font-size-12`     | 12px   | `.text-tiny`   | Tags, tiny labels, captions    |
+| `--font-size-14`     | 14px   | `.text-body-md`| Default body text, button text |
+| `--font-size-16`     | 16px   | `.text-body-lg`| Input labels, subtitles        |
+| `--font-size-18`     | 18px   | `.text-h4`     | Widget/card headings           |
+| `--font-size-24`     | 24px   | `.text-h3`     | Section headings               |
+| `--font-size-30`     | 30px   | `.text-h2`     | Page headings, footer headline |
+| `--font-size-36`+    | 36px+  | `.text-h1`     | Hero/landing headings          |
+
+## Rules
+- Always use **Manrope Bold** for headings (h1–h4)
+- Use **Nunito Sans Regular (400)** for body text
+- Use **Nunito Sans Bold (700)** for buttons and tags
+- Use **Nunito Sans SemiBold (600)** for subtitles and section labels
+- **Minimum body text size: 14px** — never use 12px for paragraph text

package/guidelines/overview-components.md

@@ -0,0 +1,19 @@
+# FlowMakers Components Overview
+
+All components are imported from `@tetjana/flowmakers-ds`.
+Always import the CSS too: `import '@tetjana/flowmakers-ds/styles'`
+
+| Component   | Purpose                                      | Guidelines file                          |
+|-------------|----------------------------------------------|------------------------------------------|
+| `Button`    | All clickable actions                        | [button.md](components/button.md)        |
+| `Input`     | Text fields, email, password, search         | [input.md](components/input.md)          |
+| `Tag`       | Labels, badges, status indicators            | [tag.md](components/tag.md)              |
+| `Toggle`    | Boolean on/off switches                      | [toggle.md](components/toggle.md)        |
+| `Checkbox`  | Multi-select options                         | [checkbox.md](components/checkbox.md)    |
+| `Header`    | Widget/card header with title and subtitle   | [header.md](components/header.md)        |
+| `Footer`    | Page footer with links and CTA               | [footer.md](components/footer.md)        |
+
+## General rules
+- Do NOT add `className` to override colors — use CSS variables instead
+- All components accept standard HTML attributes via spread props
+- Disabled state: always pass `disabled` prop, never CSS-only

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tetjana/flowmakers-ds",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "FlowMakers UI Design System — React components",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
@@ -13,24 +13,33 @@
     },
     "./styles": "./dist/styles.css"
   },
-  "files": ["dist"],
+  "files": [
+    "dist",
+    "guidelines"
+  ],
   "scripts": {
     "build": "vite build && tsc --emitDeclarationOnly --declaration --outDir dist",
-    "dev":   "vite",
-    "lint":  "eslint src"
+    "dev": "vite",
+    "lint": "eslint src"
   },
   "peerDependencies": {
-    "react":     ">=18",
+    "react": ">=18",
     "react-dom": ">=18"
   },
   "devDependencies": {
-    "@types/react":        "^18.0.0",
-    "@types/react-dom":    "^18.0.0",
-    "@vitejs/plugin-react":"^4.0.0",
-    "typescript":          "^5.0.0",
-    "vite":                "^5.0.0",
-    "vite-plugin-dts":     "^3.0.0"
+    "@figma/code-connect": "^1.4.1",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "typescript": "^5.0.0",
+    "vite": "^5.0.0",
+    "vite-plugin-dts": "^3.0.0"
   },
-  "keywords": ["flowmakers", "design-system", "react", "ui"],
+  "keywords": [
+    "flowmakers",
+    "design-system",
+    "react",
+    "ui"
+  ],
   "license": "MIT"
 }