Kanban Board Guide

The Kanban block in Ideon provides a flexible, collaborative task management system designed for agile workflows, sprint planning, and complex project coordination. This guide covers every aspect of creating and managing Kanban boards, from basic setup to advanced field configuration and team collaboration.

Getting Started

Creating a Kanban Board

1. Click the + Block button on your canvas
2. Select Kanban Block from the block menu
3. A new blank board appears with a default "TO-DO" column
4. Rename the column by clicking its title, or proceed to add tasks immediately

Basic Column Operations

Columns form the foundation of your Kanban workflow. Each column represents a stage of your process (e.g., "Backlog", "In Progress", "Review", "Done").

• Add Column: Click the + Add Column button at the right edge of your board or in the board settings
• Rename Column: Click the column header and edit the title
• Reorder Columns: Drag column headers left or right to reorganize workflow stages
• Resize Columns: Grab the column border on the right side and drag to adjust width
• Delete Column: Click the column menu (three dots) and select Delete
• Column Color: Customize each column with a color from the preset palette for visual organization
• Column Description: Add optional descriptions to columns explaining their purpose (e.g., "Features approved by Product Manager")

Adding & Managing Tasks

Tasks are the core of your Kanban board. Each task represents work to be done, assigned, tracked, and completed.

• Create Task: Click + Add Task at the bottom of any column and type a title
• Edit Task Title: Click any task to open the task modal and edit the title
• Toggle Completion: Click the checkbox on a task card to mark it complete or incomplete (completed tasks display with strikethrough text)
• Delete Task: Open the task and click the delete option, or right-click the task card
• Duplicate Task: Right-click a task card to duplicate it with all fields, then customize as needed

Task Descriptions & Rich Text

Task descriptions use Markdown syntax for rich formatting, allowing you to include detailed information, code examples, structured data, and more.

Markdown Features

Write descriptions using standard Markdown:

• Headers: # Heading 1, ## Heading 2, etc.
• Emphasis: **bold**, *italic*, ~~strikethrough~~
• Lists:
  • Unordered: - item, * item, + item
  • Ordered: 1. item, 2. item
• Links: [link text](https://example.com)
• Code:
  • Inline: `code`
  • Blocks: ```language ... ```
• Tables: Pipe-separated columns (| Header 1 | Header 2 |)
• Quotes: > quoted text

Editing Descriptions

1. Open a task by clicking on it to view the task modal
2. Scroll to the Description section
3. Click Edit to enter description editing mode
4. Write or paste Markdown-formatted text
5. Toggle Preview to see formatted result
6. Click Save or press Escape to exit editing mode

Use descriptions for:

• Detailed acceptance criteria
• Code snippets or configuration examples
• Links to related resources or tickets
• Step-by-step instructions
• Technical specifications

Custom Fields System

Custom fields extend beyond task titles and descriptions, allowing you to capture structured data like priorities, estimates, deadlines, and custom categories.

Field Types

Ideon Kanban supports four field types, each designed for different data:

1. Text Field

Simple text input for any string data.

• Use for: URLs, email addresses, ticket references, notes, free-form text
• Example: A "GitHub Issue" field storing issue URLs
• Default Value: Set initial text for new tasks (optional)
• Visibility: Toggle on/off per field; hidden fields still store data but don't display on cards

2. Date Field

Date picker for time-based information.

• Use for: Deadlines, start dates, milestones, release dates
• Example: "Due Date" field for deadline tracking
• Default Value: Set a default date or leave blank
• Interaction: Click the date picker to open a calendar; click again to clear

3. Single Select Field

Dropdown with predefined options, each with optional color coding.

• Use for: Status variants, categories, component names, priority levels
• Example: A "Priority" field with options Red (High), Orange (Medium), Green (Low)
• Color Coding: Each option displays with its assigned color on task cards for instant visual scanning
• Add Options: Create options directly in the field settings modal
• Edit Options: Rename or recolor existing options
• Default Value: Set one option as the default for newly created tasks

4. Number Field

Numeric input for quantitative data.

• Use for: Story points, complexity estimates, duration hours, issue counts
• Example: A "Story Points" field for agile estimation
• Default Value: Set initial number (optional)
• Range: No built-in min/max; teams define their own conventions

Creating & Managing Fields

Add a New Field

1. Click the Board Settings icon (gear icon) in the top-right corner of the Kanban board
2. Navigate to the Fields tab
3. Click + Add Field
4. Choose a field type (Text, Date, Single Select, Number)
5. Enter a field name (e.g., "Priority", "Story Points")
6. For Select fields: Add options with labels and optional colors
7. (Optional) Set a default value
8. Click Create Field

Edit a Field

1. Open Board Settings → Fields
2. Click the field you want to edit
3. Update the name, type, options, or default value
4. Click Save

Delete a Field

1. Open Board Settings → Fields
2. Hover over the field and click Delete
3. Confirm deletion (existing field values on tasks will be removed)

Reorder Fields

Fields appear in the order they're listed in the settings. Drag fields up or down to change their display order on task cards and in the task modal.

Filling Field Values

In Task Cards (Quick Edit)

For simple fields visible on the card:

1. Hover over the field value on the card
2. Click to edit directly (inline editing for text/number, dropdown for select, calendar for date)
3. Confirm or press Escape to cancel

In Task Modal (Full Edit)

1. Click a task to open the task modal
2. Scroll to the Fields section
3. Fill in each field:
   • Text: Type freely
   • Date: Click the date picker, select a date
   • Number: Enter numeric value
   • Select: Click to open dropdown, choose an option
4. Changes save automatically

Team Collaboration & Assignees

Kanban boards support multi-assignee task assignment, allowing teams to collaborate on tasks and clarify accountability.

Assigning Collaborators to Tasks

Add Assignees

1. Click a task to open the task modal
2. Scroll to the Assignees section
3. Click + Add Assignee or the avatar area
4. Select team members from the collaborator list
5. Select multiple collaborators by clicking each one
6. Click outside the dropdown or press Escape when done

Remove Assignees

1. Open the task modal
2. In the Assignees section, click the × button next to the assignee's name
3. The assignee is immediately removed

Viewing Assignees on Cards

• Avatar Stack: Task cards display up to 3 assignee avatars in a compact stack
• Overflow Indicator: If a task has more than 3 assignees, a "+N" badge shows the count (e.g., "+2")
• Hover for Details: Hover over the assignee area to see full names of all assigned collaborators

Permissions & Task Editing

Task editing permissions depend on a user's role in the project:

| Role | Permissions | |------|-------------| | Creator | Full edit access to all tasks, columns, and fields | | Owner | Full edit access to all tasks, columns, and fields | | Editor | Can edit task content, assignees, and custom field values | | Viewer | Read-only access; cannot modify any board elements |

Team members can edit tasks they're assigned to (if they have Editor role or higher).

Board Organization & Layout

Column Management

Beyond reordering and renaming, columns support rich configuration:

• Colors: Click the column header to access color options; choose from a preset palette
• Descriptions: Add optional text descriptions below the column title to explain its purpose or constraints
• Width Adjustment: Drag the column border to resize; minimum width ~350px prevents columns from becoming too narrow
• Lock Position: Columns maintain their order; reorder by dragging headers

Field Visibility

Not all fields need to be displayed on every task card. Configure which fields appear:

1. Click Board Settings → Field Picker
2. Toggle fields on/off to hide or show them on cards
3. Reorder visible fields to control layout priority
4. Set which fields display by default when new fields are added

This allows you to:

• Show only essential fields on cards (e.g., Priority, Due Date)
• Reduce visual clutter for teams with many custom fields
• Keep less-used fields available in the task modal for full editing

Task Card Height & Spacing

Tasks display naturally based on content. Long task titles or descriptions cause cards to expand automatically. Adjust spacing using:

• Vertical Gap: Natural spacing between cards (non-configurable; depends on card height)
• Column Width Impact: Wider columns show more text before wrapping
• Font Size: Determined by theme settings

Drag & Drop Workflows

One of Kanban's core strengths is intuitive drag-and-drop interaction, enabling fast task management without modals.

Moving Tasks Within Columns

• Reorder: Click and hold a task, drag up or down within the same column
• Drop Target: Visual line shows insertion point; release to place the task
• Bulk Moves: Single-select only (multi-select not yet supported)

Moving Tasks Between Columns

• Cross-Column Transfer: Drag a task to a different column in the same board
• Visual Feedback: Column highlights when you hover over it with a dragged task
• Automatic Status: Moving a task to "Done" doesn't automatically check completion; manage separately

Moving Tasks Between Kanban Blocks

• Cross-Block Transfer: Drag a task from one Kanban board to another on the same canvas
• Field Handling: If the destination board has different fields, the task keeps its field values where field names match; extra fields are ignored
• Column Selection: Drop the task on a specific column in the destination board

Transferring from Checklist Blocks

• Checklist to Kanban: Drag a checklist item directly onto a Kanban column to convert it to a task
• Preserves Content: Task title and completion status transfer; descriptions don't (checklist items are plain text)
• Kanban to Checklist: Move a Kanban task back to a checklist; only title and completion status transfer

Moving Entire Columns

• Column Migration: Drag a column header to move the entire column (with all tasks) to another position
• Same Board: Reorder workflow stages by dragging columns left/right
• Different Board: Drag a column header across boards to transfer it with all tasks (copying behavior may vary; check current version)

Advanced Workflows

Sprint Planning with Kanban

1. Create columns: "Backlog", "Sprint Planning", "Ready", "In Progress", "Review", "Done"
2. Add a "Story Points" number field for estimation
3. Add a "Sprint" single-select field (values: Sprint 1, Sprint 2, etc.)
4. Use assignees to clarify team responsibility
5. Drag tasks through columns as work progresses
6. At sprint end, archive "Done" column or reset the board

Bug Tracking

1. Create columns: "Reported", "Confirmed", "In Progress", "Fixed", "Closed"
2. Add fields: "Severity" (select: Critical, High, Medium, Low), "Bug ID" (text), "Found Date" (date module), "Rep Steps" (description)
3. Use checkbox to mark fixed bugs
4. Assign to developers; use descriptions for reproduction steps

Feature Prioritization

1. Create columns reflecting decision stages: "Requested", "Evaluating", "Approved", "Scheduled", "In Development", "Shipped"
2. Add fields: "Priority" (select: High, Medium, Low), "Risk Level" (select: Low, Medium, High), "Dev Effort" (story points)
3. Use descriptions for feature rationale and customer feedback
4. Color-code priority select options for quick scanning

Kanban as a Persistent Dashboard

1. Create a single "View" Kanban board that stays open during meetings
2. Add tasks as action items with assignees and due dates
3. Use "In Progress" and "Done" columns to track real-time progress
4. Reference from other projects via cross-project links

Tips & Best Practices

Performance

• Large Boards: Boards with 500+ tasks may experience slower drag-drop; consider archiving completed items
• Field Count: Limit visible fields to 5-7 for optimal card readability; hide less-used fields in picker

Data Organization

• Naming Conventions: Use consistent column names across projects (e.g., always "In Progress" not "WIP")
• Field Defaults: Set defaults to reduce repetitive data entry (e.g., all new bugs default to "Open" status)
• Color Consistency: Use the same colors for the same meaning across boards (e.g., red always = high priority)

Team Usage

• Role Clarity: Ensure team members understand their editing permissions (Viewer = read-only, Editor = modify)
• Assignment Clarity: Always assign tasks to clarify ownership; multi-assign for pair work
• Regular Review: Archive or clear completed tasks weekly to keep the board scannable

Integration Patterns

• With Checklist Blocks: Use Checklists for fine-grained subtasks, Kanban for top-level work phases
• With Note Blocks: Keep project brief or strategic notes in a companion Note block; link from column descriptions
• With Link Blocks: Reference external tickets (GitHub, Jira) via text fields storing URLs

Keyboard Shortcuts

Currently, Kanban blocks integrate with canvas-level keyboard navigation. Task-specific shortcuts will be added in future releases. For now:

• Canvas Navigation: Use arrow keys to move between selected blocks
• Task Opening: Click to open task modals (keyboard shortcut for this coming soon)
• Escape: Close modals and deselect cards

Troubleshooting

Tasks Don't Appear in Column

• Ensure the column exists and isn't deleted
• Check field visibility; if a field is required and missing, the task may not render (partial fix in progress)
• Verify permissions; Viewer role can't create tasks

Custom Fields Not Saving

• Refresh the page to sync with server
• Check browser console (F12) for errors
• Ensure field type matches expected data (e.g., date field requires valid date format)

Assignees Removed on Sync

• If an assignee is removed from the project, their assignment is purged on next sync
• Re-assign from remaining collaborators if needed

Drag-Drop Not Working

• Ensure you're not in edit mode for a task or field
• Try clicking elsewhere first to deselect, then attempt drag
• Use Firefox or Chrome; some edge cases exist in other browsers

Board Won't Load

• Very large boards (1000+ tasks) may take 5-10 seconds to render initially
• Check browser console for client errors
• Try refreshing; if persistent, report the issue with board size/field count

API & Advanced Integration

For developers integrating Kanban with external systems:

• Data Structure: Kanban data is stored in block metadata as JSON with columns, tasks, and fields nested structure
• Real-time Sync: Changes propagate via Yjs; modifications sync across all connected clients instantly
• No REST API Yet: Direct API access to Kanban data is not yet available; use web UI for modifications

See the API Documentation for more details on block-level data access.

What's Next

Future Kanban enhancements planned include:

• Advanced filtering and search across all fields
• Kanban board templates for common workflows
• Inline multi-task editing
• Card count limits per column
• Archive and history views
• Markdown-based bulk task import/export