---
epic: 2
story: 2.6
title: "Custom User-Defined Units"
status: draft
---

## Epic 2 — Unit Conversion System
**Goal:** Support 200+ units across all major categories with SI prefix support.

### Story 2.6: Custom User-Defined Units

As a CalcPad user,
I want to define my own units such as `1 sprint = 2 weeks` or `1 story_point = 4 hours`,
So that I can use domain-specific units in my calculations.

**Acceptance Criteria:**

**Given** the user writes `1 sprint = 2 weeks` on a line
**When** the engine evaluates the sheet
**Then** it registers `sprint` as a custom unit convertible to and from `weeks`
**And** subsequent lines can use `sprint` in expressions

**Given** a custom unit `1 sprint = 2 weeks` is defined
**When** the expression `3 sprints in days` is evaluated
**Then** the result is `42 days`

**Given** a custom unit `1 story_point = 4 hours` is defined
**When** the expression `10 story_points in hours` is evaluated
**Then** the result is `40 hours`

**Given** a custom unit is defined in one sheet
**When** the user configures it as a global custom unit
**Then** it is available in all sheets
**And** sheet-local definitions override global ones if there is a name conflict

**Given** a custom unit definition that creates a circular dependency (e.g., `1 foo = 2 bar` and `1 bar = 3 foo`)
**When** the engine processes these definitions
**Then** it detects the circular dependency and returns an error
**And** it does not enter an infinite loop

**Given** a custom unit name that conflicts with a built-in unit name
**When** the user defines it
**Then** the engine warns that the built-in unit is being shadowed
**And** the custom definition takes precedence within that sheet