@acjlabs/apparel-attribute-utils

Zero-dependency apparel size and color canonicalization. TypeScript, works in Node, Bun, Deno, and the browser — no network calls, no external services, no LLM.

Install

npm install @acjlabs/apparel-attribute-utils

What's in it

Size normalization

import { normalizeSize } from "@acjlabs/apparel-attribute-utils";

normalizeSize("Medium"); // "M"
normalizeSize("2XL"); // "XXL"
normalizeSize("x-small"); // "XS"
normalizeSize("32x34"); // "32x34" — numeric sizes pass through unchanged
normalizeSize("this shirt runs medium-ish"); // null — no guessing

Canonicalizes letter sizes and their common synonyms/abbreviations (XXS/XS/S/M/L/XL/XXL/XXXL) case- and whitespace-insensitively. Numeric sizes (waist, inseam, shoe size — "32", "10.5", "32x34") pass through unchanged since they're already unambiguous. Anything it doesn't recognize returns null rather than a guess.

Color normalization

import { normalizeColor } from "@acjlabs/apparel-attribute-utils";

normalizeColor("navy blue"); // "navy"
normalizeColor("Heather Gray"); // "gray"
normalizeColor("rose gold"); // "rose"
normalizeColor("a lovely shade of blue-ish grey"); // null — no guessing

Canonicalizes ~90 common color-name synonyms down to a controlled vocabulary of 25 apparel colors (see COLORS export) — distinguishing visually distinct families a naive "20 basic colors" list collapses, like off-white vs. white, charcoal vs. gray, rose/lavender as their own pastel buckets, and gold as a metallic distinct from yellow. Unrecognized input returns null.

Why this exists

We build Catalog Attribute Normalizer, a hosted API/MCP server that cleans messy merchant product data and maps it to taxonomy paths using LLM classification. This package is the small, deterministic piece of that: the actual size/color canonicalization rules, with no model call, no hosting, no API key — just the lookup tables and normalization logic, MIT-licensed, for anyone who needs that piece on its own (a catalog importer, a feed-cleanup script, a CSV normalizer).

Scope

Deliberately conservative by design: both functions return null for anything outside their controlled vocabulary rather than guess. If you need free-text/ambiguous size or color descriptions resolved (not just already-recognizable synonyms canonicalized), that's a classification problem this package doesn't attempt — see Catalog Attribute Normalizer above for that.

License

MIT