@tetjana/flowmakers-ds 0.1.8 → 0.1.10

package/guidelines/components/question.md

@@ -0,0 +1,65 @@
+# Question (FAQ Accordion)
+
+An expandable FAQ item. Click to reveal the answer. Used on landing pages and help sections.
+
+## Import
+```tsx
+import { Question } from '@tetjana/flowmakers-ds';
+import '@tetjana/flowmakers-ds/styles';
+```
+
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | `"Що таке Rework?"` | Question text |
+| `text` | `string` | `"..."` | Answer text (shown when open) |
+| `open` | `boolean` | `false` | Whether the accordion is expanded |
+| `state` | `'default' \| 'hover'` | `'default'` | Visual state (hover = pink border) |
+| `onClick` | `() => void` | — | Toggle handler |
+| `className` | `string` | — | Extra CSS class |
+
+## States
+- **default** — closed, gray border (`#eeeef0`), purple `+` icon
+- **hover** — closed, pink border (`#ffa8f1`), purple `+` icon
+- **open** — expanded with answer text, pink border, dark `×` icon
+
+## Usage
+
+### Static showcase
+```tsx
+<Question title="Що таке Rework?" state="default" />
+<Question title="Як розпочати?" state="hover" />
+<Question title="Які тарифи?" open text="Базовий, Стандарт, Преміум." />
+```
+
+### Interactive FAQ list
+```tsx
+const [openIndex, setOpenIndex] = useState<number | null>(null);
+
+const faqs = [
+  { title: 'Що таке Rework?', text: 'AI-платформа для кар\'єри...' },
+  { title: 'Як розпочати?',   text: 'Зареєструйтеся і...' },
+];
+
+return faqs.map((faq, i) => (
+  <Question
+    key={i}
+    title={faq.title}
+    text={faq.text}
+    open={openIndex === i}
+    onClick={() => setOpenIndex(openIndex === i ? null : i)}
+  />
+));
+```
+
+## Design
+- Container: `border-radius: 20px`, `padding: 20px 16px`
+- Title: Manrope SemiBold 20px, `#121212`
+- Answer: Nunito Sans Light 16px, `#121212`, `line-height: 1.4`
+- Icon: 33px circle, purple (`#9076dc`) when closed, dark (`#18181b`) when open
+- Border transition: `0.15s`
+
+## When to use
+- FAQ sections on landing pages
+- Help/documentation pages
+- Any expandable question-answer content

package/guidelines/components/radiobutton.md

@@ -0,0 +1,57 @@
+# RadioButton
+
+Single radio input with a custom-styled circle indicator and an optional label. Fully controlled — manage the `checked` state in the parent component.
+
+## Import
+```tsx
+import { RadioButton } from '@tetjana/flowmakers-ds';
+import '@tetjana/flowmakers-ds/styles';
+```
+
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | — | Text label shown next to the button |
+| `checked` | `boolean` | `false` | Whether the radio is selected |
+| `disabled` | `boolean` | — | Disables interaction |
+| `onChange` | `React.ChangeEventHandler<HTMLInputElement>` | — | Change handler |
+| `className` | `string` | — | Extra CSS class on the wrapper `<label>` |
+| `...rest` | `InputHTMLAttributes<HTMLInputElement>` | — | All native `<input type="radio">` attributes (name, value, etc.) |
+
+## Usage
+
+```tsx
+// Controlled radio group
+const [plan, setPlan] = useState('basic');
+
+<RadioButton
+  label="Базовий"
+  name="plan"
+  value="basic"
+  checked={plan === 'basic'}
+  onChange={() => setPlan('basic')}
+/>
+<RadioButton
+  label="Про"
+  name="plan"
+  value="pro"
+  checked={plan === 'pro'}
+  onChange={() => setPlan('pro')}
+/>
+
+// Disabled
+<RadioButton label="Преміум (незабаром)" disabled />
+```
+
+## Design
+- Wrapper `<label>`: `display: flex`, `align-items: center`, `gap: 8px`, `cursor: pointer`
+- Circle: `18×18px`, `border: 2px solid #eeeef0`, `border-radius: 9999px`
+- Checked circle: border-color `#9076dc`, inner dot `8×8px` filled `#9076dc`
+- Disabled: `opacity: 0.5`, `cursor: not-allowed`
+- Label: Nunito Sans Regular 14px, `#18181b`
+- Native `<input>` is visually hidden (`sr-only`)
+
+## When to use
+- Mutually exclusive option groups (plan selection, gender, sorting)
+- Use multiple `RadioButton` components sharing the same `name` prop
+- For a full plan card with price + features, use `Price` or `PriceCard` instead

package/guidelines/components/search.md

@@ -0,0 +1,41 @@
+# Search
+
+Text input with a built-in search icon. Used in dashboards and filter areas for quick content filtering.
+
+## Import
+```tsx
+import { Search } from '@tetjana/flowmakers-ds';
+import '@tetjana/flowmakers-ds/styles';
+```
+
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `placeholder` | `string` | `'Пошук...'` | Input placeholder text |
+| `className` | `string` | — | Extra CSS class on the wrapper |
+| `...rest` | `InputHTMLAttributes<HTMLInputElement>` | — | All native `<input>` attributes (value, onChange, onKeyDown, etc.) |
+
+## Usage
+
+```tsx
+// Uncontrolled
+<Search placeholder="Знайти вакансію..." />
+
+// Controlled
+const [q, setQ] = useState('');
+<Search
+  value={q}
+  onChange={e => setQ(e.target.value)}
+  placeholder="Пошук по резюме..."
+/>
+```
+
+## Design
+- Wrapper: `display: flex`, `align-items: center`, `gap: 8px`, `border: 1px solid #eeeef0`, `border-radius: 12px`, `padding: 8px 12px`
+- Icon: `20×20px`, stroke `#91939f`
+- Input: no native border, full-width, Nunito Sans Regular 14px, `#18181b`
+
+## When to use
+- Dashboard search bars
+- Filter inputs for lists or tables
+- Combine with `Dropdown` for filter + search patterns

package/guidelines/components/sectiontitle.md

@@ -0,0 +1,74 @@
+# SectionTitle
+
+Landing page section heading with optional tag badge, title, and subtitle. Supports three layout variants.
+
+## Import
+```tsx
+import { SectionTitle } from '@tetjana/flowmakers-ds';
+import { type SectionTitleVariant } from '@tetjana/flowmakers-ds';
+import '@tetjana/flowmakers-ds/styles';
+```
+
+## Types
+
+```ts
+type SectionTitleVariant = 'centered' | 'split' | 'left';
+```
+
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tag` | `string` | `'Можливості платформи'` | Text for the `TagBig` badge above the title |
+| `showTag` | `boolean` | `true` | Whether to show the tag badge |
+| `title` | `string` | `"Все для твоєї кар'єри"` | Main section heading |
+| `subtitle` | `string` | `'Комплексна платформа...'` | Supporting paragraph |
+| `showSubtitle` | `boolean` | `true` | Whether to show the subtitle |
+| `variant` | `SectionTitleVariant` | `'centered'` | Layout variant |
+| `className` | `string` | — | Extra CSS class |
+
+## Usage
+
+```tsx
+// Centered (default) — used in most sections
+<SectionTitle
+  tag="Переваги"
+  title="Чому обирають нас"
+  subtitle="Платформа, яка реально допомагає знайти роботу"
+/>
+
+// Split — title left, subtitle right (2-column layout)
+<SectionTitle
+  variant="split"
+  tag="Тарифи"
+  title="Обери свій план"
+  subtitle="Гнучкі тарифи для будь-якого рівня"
+/>
+
+// Left-aligned — no centering
+<SectionTitle
+  variant="left"
+  tag="Блог"
+  title="Останні статті"
+  showSubtitle={false}
+/>
+```
+
+## Variants
+
+| Variant | Layout |
+|---------|--------|
+| `centered` | Tag + title + subtitle stacked, center-aligned |
+| `split` | Tag + title on left, subtitle on right (flex row) |
+| `left` | Tag + title + subtitle stacked, left-aligned |
+
+## Design
+- Uses `TagBig` internally for the badge (with `showIcon={false}`)
+- Heading (`<h2>`): Manrope Bold 40px, `#18181b`
+- Subtitle: Nunito Sans Regular 18px, `#5d5e6c`, `max-width: 560px`
+- Centered variant: `text-align: center`, `align-items: center`
+- Split variant: `display: flex`, `justify-content: space-between`, `align-items: flex-end`
+
+## When to use
+- Opening of every landing page section
+- Replaces manually building tag + heading + subtitle every time
+- Do not use `SectionTitle` inside the dashboard — use `DashboardTitle` instead

package/guidelines/components/signupform.md

@@ -0,0 +1,40 @@
+# SignupForm
+
+Email capture form with a CTA button. Typically used in hero sections and landing page footers.
+
+## Import
+```tsx
+import { SignupForm } from '@tetjana/flowmakers-ds';
+import '@tetjana/flowmakers-ds/styles';
+```
+
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `placeholder` | `string` | `'Ваша електронна пошта'` | Input placeholder text |
+| `buttonLabel` | `string` | `'Почати безкоштовно'` | CTA button text |
+| `onSubmit` | `(email: string) => void` | — | Called on form submit with the email value |
+| `className` | `string` | — | Extra CSS class |
+
+## Usage
+
+```tsx
+<SignupForm
+  placeholder="Ваша електронна пошта"
+  buttonLabel="Почати безкоштовно"
+  onSubmit={(email) => console.log('Submitted:', email)}
+/>
+```
+
+## Design
+- Container: `background: white`, `border-radius: 20px`, `padding: 10px 20px`
+- Input: Nunito Sans Light 16px, transparent background, full flex width
+- Placeholder color: `#5d5e6c` (nature-fill-600)
+- Button: black bg (`#121212`), white text, `border-radius: 12px`, height `42px`
+- Internally controlled — email value is managed with `useState`
+
+## When to use
+- Hero CTA sections on landing pages
+- Newsletter subscription
+- Waitlist sign-up
+- Do NOT use for complex multi-field forms (use `Input` + `Button` separately)

package/guidelines/components/stepper.md

@@ -0,0 +1,61 @@
+# Stepper
+
+Horizontal step indicator with numbered circles and connector lines. Shows multi-step progress (e.g. onboarding, form wizard).
+
+## Import
+```tsx
+import { Stepper } from '@tetjana/flowmakers-ds';
+import { type StepperStep, type StepperStepState } from '@tetjana/flowmakers-ds';
+import '@tetjana/flowmakers-ds/styles';
+```
+
+## Types
+
+```ts
+type StepperStepState = 'done' | 'in-process' | 'inactive';
+
+interface StepperStep {
+  label: string;
+  state: StepperStepState;
+}
+```
+
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `steps` | `StepperStep[]` | required | Ordered list of steps with label and state |
+| `className` | `string` | — | Extra CSS class |
+
+## Usage
+
+```tsx
+<Stepper
+  steps={[
+    { label: 'Реєстрація',    state: 'done' },
+    { label: 'Профіль',       state: 'in-process' },
+    { label: 'Тестування',    state: 'inactive' },
+    { label: 'Результат',     state: 'inactive' },
+  ]}
+/>
+```
+
+## Step states
+
+| State | Circle | Line | Label |
+|-------|--------|------|-------|
+| `done` | Purple fill, white check ✓ | Purple | Gray muted |
+| `in-process` | Purple fill, white number | Purple | Dark `#18181b` |
+| `inactive` | Gray outline, gray number | Gray | Gray muted |
+
+## Design
+- Layout: `display: flex`, `align-items: flex-start`, `gap: 0` (steps stretch with lines between)
+- Circle: `32×32px`, `border-radius: 50%`
+- Done/in-process circle: `background: #9076dc`
+- Inactive circle: `border: 2px solid #eeeef0`, transparent
+- Line: `height: 2px`, grows to fill space between circles (`flex: 1`)
+- Label: Nunito Sans 12px, positioned below the circle
+
+## When to use
+- Multi-step forms (profile setup, checkout)
+- Onboarding wizards
+- Use `StepperProgress` for a vertical sidebar-style progress tracker instead

package/guidelines/components/stepperprogress.md

@@ -0,0 +1,62 @@
+# StepperProgress
+
+Vertical progress tracker with checkmark circles and connecting lines. Used in sidebars and dashboards to show task/step completion.
+
+## Import
+```tsx
+import { StepperProgress } from '@tetjana/flowmakers-ds';
+import { type StepperProgressStep, type StepperProgressState } from '@tetjana/flowmakers-ds';
+import '@tetjana/flowmakers-ds/styles';
+```
+
+## Types
+
+```ts
+type StepperProgressState = 'done' | 'in-process' | 'inactive';
+
+interface StepperProgressStep {
+  label: string;
+  state?: StepperProgressState;  // defaults to 'inactive'
+}
+```
+
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `steps` | `StepperProgressStep[]` | required | Ordered list of steps |
+| `className` | `string` | — | Extra CSS class |
+
+## Usage
+
+```tsx
+<StepperProgress
+  steps={[
+    { label: 'Завантажити резюме',       state: 'done' },
+    { label: 'Пройти AI-тест',           state: 'in-process' },
+    { label: 'Переглянути рекомендації', state: 'inactive' },
+    { label: 'Надіслати заявку',         state: 'inactive' },
+  ]}
+/>
+```
+
+## Step states
+
+| State | Circle | Line | Label |
+|-------|--------|------|-------|
+| `done` | Purple fill, white ✓ | Purple solid | Muted gray |
+| `in-process` | Purple fill, white ✓ | Gray dashed | Dark `#18181b` |
+| `inactive` | Gray outline, no check | Gray dashed | Muted gray |
+
+## Design
+- Layout: `display: flex`, `flex-direction: column`, `gap: 0`
+- Circle: `24×24px`, `border-radius: 50%`
+- Done/in-process circle: `background: #9076dc`
+- Inactive circle: `border: 2px solid #eeeef0`
+- Connector line: `width: 2px`, `height: 24px`, centered below circle
+- Label: Nunito Sans Regular 14px, positioned to the right of the circle
+
+## When to use
+- Dashboard sidebar progress lists
+- Onboarding checklists
+- Step-by-step task completion tracking
+- Use `Stepper` (horizontal) for wizard-style multi-step navigation instead

package/guidelines/components/tagbig.md

@@ -0,0 +1,39 @@
+# TagBig
+
+A large pill-shaped tag with an optional sparkle icon. Used as a section label / badge above headings on landing pages.
+
+## Import
+```tsx
+import { TagBig } from '@tetjana/flowmakers-ds';
+import '@tetjana/flowmakers-ds/styles';
+```
+
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | `"АІ-помічник для кар'єрного розвитку"` | Text content of the tag |
+| `showIcon` | `boolean` | `true` | Show the sparkle gradient icon before the text |
+| `className` | `string` | — | Extra CSS class |
+
+## Usage
+
+```tsx
+// Default — with sparkle icon
+<TagBig label="Нові можливості" />
+
+// Without icon (used inside SectionTitle split variant)
+<TagBig label="Про платформу" showIcon={false} />
+
+// Custom label
+<TagBig label="Бета-версія" />
+```
+
+## Design
+- Container: `display: inline-flex`, `align-items: center`, `gap: 6px`, `border: 1px solid #eeeef0`, `border-radius: 9999px`, `padding: 6px 12px`, `background: #ffffff`
+- Icon: `16×16px` sparkle SVG, purple-to-pink gradient (`#9076dc` → `#ffa8f1`)
+- Label: Nunito Sans SemiBold 14px, `#18181b`
+
+## When to use
+- Section labels above hero headings (`<SectionTitle tag="..." />` uses it internally)
+- Feature badges
+- Note: `SectionTitle` with `showTag` uses `TagBig` automatically — use standalone `TagBig` only when you need it outside a section title context

package/guidelines/components/tariffs.md

@@ -0,0 +1,57 @@
+# Tariffs
+
+A plan/tier selection card with icon, title, and description. Used in pricing or plan-selection flows.
+
+## Import
+```tsx
+import { Tariffs } from '@tetjana/flowmakers-ds';
+import '@tetjana/flowmakers-ds/styles';
+```
+
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `icon` | `ReactNode` | — | Icon element (displayed in a purple-tint box) |
+| `title` | `string` | `'Базовий'` | Plan name |
+| `description` | `string` | `'Ідеальний старт...'` | Short description of the plan |
+| `variant` | `'default' \| 'hover'` | `'default'` | Visual state |
+| `className` | `string` | — | Extra CSS class |
+
+## Variants
+- **default** — white bg, gray border (`#eeeef0`)
+- **hover** — white bg, pink border (`#ffa8f1`)
+
+## Usage
+
+```tsx
+import { Tariffs } from '@tetjana/flowmakers-ds';
+
+const PlanIcon = () => <svg>...</svg>;
+
+// Default plan card
+<Tariffs
+  icon={<PlanIcon />}
+  title="Базовий"
+  description="Ідеальний старт для знайомства з платформою."
+/>
+
+// Highlighted (selected/hover) state
+<Tariffs
+  icon={<PlanIcon />}
+  title="Про"
+  description="Максимальні можливості для активного пошуку роботи."
+  variant="hover"
+/>
+```
+
+## Design
+- Layout: `flex`, `align-items: center`, `gap: 20px`, `padding: 20px`
+- Icon box: `40×40px`, `background: #e0ddf7` (primary-fill-200), `border-radius: 4px`
+- Title: Manrope SemiBold 20px, `#18181b`
+- Description: Nunito Sans Light 12px, `#4c4d58`
+- Border-radius: 12px
+
+## When to use
+- Pricing/plan selection UI
+- Feature comparison rows
+- Settings plan display

package/guidelines/components/taskswidget.md

@@ -0,0 +1,68 @@
+# TasksWidget
+
+A dashboard widget that displays a list of tasks with completion status and optional time tags. Shows a checkmark for done items and strikethrough text.
+
+## Import
+```tsx
+import { TasksWidget } from '@tetjana/flowmakers-ds';
+import { type TaskItem } from '@tetjana/flowmakers-ds';
+import '@tetjana/flowmakers-ds/styles';
+```
+
+## Types
+
+```ts
+interface TaskItem {
+  label: string;
+  done?:  boolean;
+  time?:  string;
+}
+```
+
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tasks` | `TaskItem[]` | required | List of tasks to render |
+| `className` | `string` | — | Extra CSS class |
+
+## Usage
+
+```tsx
+<TasksWidget
+  tasks={[
+    { label: 'Оновити резюме',              done: true,  time: '09:00' },
+    { label: 'Пройти тест на увагу',        done: true },
+    { label: 'Переглянути вакансії',        done: false, time: '14:00' },
+    { label: 'Надіслати заявку в компанію', done: false },
+  ]}
+/>
+
+// Minimal — no time tags
+<TasksWidget
+  tasks={[
+    { label: 'Завершити профіль', done: true },
+    { label: 'Додати фото',       done: false },
+  ]}
+/>
+```
+
+## Task item anatomy
+Each row contains:
+1. **Checkbox** — `20×20px` circle; filled purple (`#9076dc`) + white check when `done`, empty gray outline when not done
+2. **Label** — task text; strikethrough + muted color when `done`
+3. **Time tag** (optional) — small pill badge showing the time string
+
+## Design
+- Container: `display: flex`, `flex-direction: column`, `gap: 12px`
+- Row: `display: flex`, `align-items: center`, `gap: 12px`
+- Checkbox: `20×20px`, `border-radius: 50%`
+  - Done: `background: #9076dc`, white ✓ SVG
+  - Pending: `border: 2px solid #eeeef0`, transparent bg
+- Label: Nunito Sans Regular 14px, `#18181b`
+  - Done label: `text-decoration: line-through`, color `#91939f`
+- Time tag: `background: #f7f7f8`, `border-radius: 8px`, `padding: 2px 8px`, Nunito Sans SemiBold 12px, `#5d5e6c`
+
+## When to use
+- Dashboard home pages (daily task list)
+- Sidebar to-do widgets
+- Progress summaries in onboarding flows

package/guidelines/components/testimonialcard.md

@@ -0,0 +1,50 @@
+# TestimonialCard
+
+Displays a user quote with avatar, name, and role. Used in social proof / reviews sections.
+
+## Import
+```tsx
+import { TestimonialCard } from '@tetjana/flowmakers-ds';
+import '@tetjana/flowmakers-ds/styles';
+```
+
+## Props
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✅ | Author's full name |
+| `quote` | `string` | ✅ | Review / testimonial text |
+| `avatar` | `string` | — | URL of avatar image |
+| `role` | `string` | — | Job title or description |
+| `className` | `string` | — | Extra CSS class |
+
+## Usage
+
+```tsx
+<TestimonialCard
+  name="Олена Ковальська"
+  role="Front-end Developer"
+  quote="Завдяки Rework я знайшла нову роботу за 3 тижні. Тести дійсно показали мої слабкі місця."
+  avatar="/avatars/olena.jpg"
+/>
+```
+
+## Without avatar (uses first letter as placeholder)
+```tsx
+<TestimonialCard
+  name="Максим Петренко"
+  role="Product Manager"
+  quote="Найкраща платформа для кар'єрного зростання."
+/>
+```
+
+## Design
+- Container: `width: 351px`, `border: 1px solid #eeeef0`, `border-radius: 20px`, `padding: 32px 24px`, `gap: 24px`
+- Avatar: `30×30px`, circle
+- Name: Nunito Sans Bold 12px, `#18181b`
+- Role: Nunito Sans Light 12px, `#18181b`
+- Quote: Nunito Sans Light 18px, `line-height: 1.12`
+
+## When to use
+- Social proof sections on landing pages
+- Customer reviews
+- Use in a horizontal scroll or grid layout (typically 3 per row)

package/guidelines/components/timepicker.md

@@ -0,0 +1,58 @@
+# TimePicker
+
+Time input field with label, helper text, and visual states. Mirrors the `DatePicker` API but uses `<input type="time">` with a clock icon.
+
+## Import
+```tsx
+import { TimePicker } from '@tetjana/flowmakers-ds';
+import { type TimePickerState } from '@tetjana/flowmakers-ds';
+import '@tetjana/flowmakers-ds/styles';
+```
+
+## Types
+
+```ts
+type TimePickerState = 'default' | 'hover' | 'focused' | 'disabled';
+```
+
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | — | Label displayed above the field |
+| `helperText` | `string` | — | Helper/error text below the field |
+| `state` | `TimePickerState` | `'default'` | Visual state |
+| `disabled` | `boolean` | — | Disables input (also triggered by `state='disabled'`) |
+| `className` | `string` | — | Extra CSS class on the wrapper |
+| `...rest` | `InputHTMLAttributes<HTMLInputElement>` | — | All native `<input>` attributes (value, onChange, etc.) |
+
+## Usage
+
+```tsx
+// Basic
+<TimePicker label="Час початку" />
+
+// Controlled with helper
+<TimePicker
+  label="Час зустрічі"
+  helperText="Робочі години: 09:00–18:00"
+  value={time}
+  onChange={e => setTime(e.target.value)}
+/>
+
+// Disabled
+<TimePicker label="Час закінчення" state="disabled" />
+```
+
+## Design
+Identical to `DatePicker` layout and styling — differs only in icon (clock instead of calendar) and input type.
+
+- Container: `display: flex`, `flex-direction: column`, `gap: 4px`
+- Label: Nunito Sans SemiBold 14px, `#18181b`
+- Field: `border: 1px solid #eeeef0`, `border-radius: 12px`, `padding: 10px 12px`, `height: 42px`
+- Focused state: border-color `#9076dc`
+- Disabled state: background `#f7f7f8`, opacity `0.6`
+
+## When to use
+- Scheduling forms (pair with `DatePicker` for full datetime input)
+- Meeting / event booking
+- Availability selection