Linear

Hierarch syncs with Linear to bring issue tracking into your design workflow. You can view, create, and update Linear issues directly inside Hierarch, attach Figma files to issues, and overlay design- specific metadata (design type, checklist, phase) on top of your existing Linear data.

Authentication

The Linear integration uses OAuth 2.0. When registering Hierarch as a Linear OAuth application, use the following configuration:

Application Name	Hierarch
Redirect URI (prod)	https://hierarch.vercel.app/api/auth/callback/linear
Redirect URI (dev)	http://localhost:3000/api/auth/callback/linear
Webhook URL	https://hierarch.vercel.app/api/webhooks/linear (optional)

Required OAuth Scopes

read	Read access to the user's Linear workspace data
write	Create and update issues, attachments, and comments
issues:create	Create new issues in any team the user has access to
issues:write	Update existing issue fields (status, title, description, priority)

API Details

All communication with Linear uses the GraphQL API at https://api.linear.app/graphql. Hierarch sends POST requests with a JSON body containing the query and variables.

GraphQL Operations

Operation	Type	Description
getViewer	Query	Fetch the authenticated user (id, name, email, avatarUrl)
getTeams	Query	List all teams in the workspace (id, name)
getTeamStatuses	Query	List workflow statuses for a team (id, name, type, color)
getIssues	Query	List all issues for a team with full fields
createIssue	Mutation	Create a new issue (title, description, teamId, priority, stateId)
updateIssue	Mutation	Update issue fields (title, description, priority, stateId)
getAttachments	Query	List attachments on an issue
createAttachment	Mutation	Attach a URL (Figma file) to an issue
deleteAttachment	Mutation	Remove an attachment from an issue

Data Hierarch Reads

Authenticated user profile (viewer query)
Teams and their workflow statuses
Issues for the selected team (all fields: identifier, title, description, priority, status, labels, assignee, dates)
Attachments on individual issues

Data Hierarch Writes

New issues (via issueCreate mutation)
Issue updates: title, description, priority, stateId (via issueUpdate mutation)
Figma file attachments on issues (via attachmentCreate/attachmentDelete mutations)

Hierarch does not modify team settings, workspace configuration, labels, or any data outside of individual issues and their attachments.

Design Metadata

Hierarch overlays additional design-specific metadata on Linear issues. This metadata is stored per-user and keyed by Linear issue ID. It is never pushed to Linear, keeping your Linear workspace clean while giving designers additional context.

DesignMeta Schema

{
  figmaUrl?: string,         // Figma file URL
  designType?: "ui" | "ux" | "brand" | "motion" | "prototype" | "copy",
  checklist: [               // Default items:
    "Specs",
    "Responsive/breakpoints",
    "Dark mode",
    "A11y",
    "Dev handoff ready"
  ]
}

Figma Attachment Sync

When a user adds a Figma URL to a Linear issue's design metadata in Hierarch, the URL is synced to Linear as an attachment. The sync logic runs on focus and blur events:

On focus: Hierarch fetches existing attachments for the issue and checks for an existing Figma URL.
On blur: If the Figma URL changed, Hierarch creates a new attachment (or deletes the old one if the URL was cleared).

An oEmbed thumbnail is fetched from Figma for preview rendering inside the Hierarch issue drawer.

Data Types

LinearIssue

{
  id: string,
  identifier: string,      // e.g. "ENG-123"
  title: string,
  description: string,
  priority: number,        // 0 (none) to 4 (urgent)
  url: string,
  status: LinearStatus,
  labels: LinearLabel[],
  assignee?: LinearUser,
  createdAt: string,
  updatedAt: string
}

LinearStatus

{
  id: string,
  name: string,           // e.g. "In Progress"
  type: string,           // e.g. "started", "completed"
  color: string           // hex color
}

LinearLabel

{
  id: string,
  name: string,
  color: string
}